docs: rename Academy articles #1639
Conversation
Rename to avoid confusion & make titles more action-oriented
TC-MO
added
documentation
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
| @@ -57,7 +55,7 @@ One important thing to note is that you can use a `.gitignore` file to exclude f | |||
|
|
|||
| ## Deployed! {#deployed} | |||
|
|
|||
| Great! Once you've pushed your Actor to the platform, you should see it in the list of Actors under the **Actors** tab. If you used `apify push`, you'll have access to the **multifile editor** (discussed [here](../getting_started/creating_actors.md)). | |||
| Great! Once you've pushed your Actor to the platform, you should see it in the list of Actors under the **Actors** tab. If you used `apify push`, you'll have access to the **multifile editor** (discussed in [Creating Actors](../getting_started/creating_actors.md)). | |||
There was a problem hiding this comment.
It would be nicer to have the hyperlink directly underneath the text instead of having a clause with "discussed in X" or "discussed here".
Also, when I open the page, there's nothing about a multifile editor. As a reader (and even as an Apify emploee), I don't know what that is from that page, so the link doesn't really help me.
There was a problem hiding this comment.
I've updated the link to speficially go to #web-ide section of the Creating Actors page. But anything more would require a big rewrite, which is not the point of this change. I can attempt it but this will balloon this rather simple PR into something much more substantial
There was a problem hiding this comment.
Ok, I see. What about the first part of the comment? :)
| @@ -20,7 +18,7 @@ The **Dockerfile** is a file which gives the Apify platform (or Docker, more spe | |||
|
|
|||
| ## Base images {#base-images} | |||
|
|
|||
| If your project doesn’t already contain a Dockerfile, don’t worry! Apify offers [many base images](/sdk/js/docs/guides/docker-images) that are optimized for building and running Actors on the platform, which can be found [here](https://hub.docker.com/u/apify). When using a language for which Apify doesn't provide a base image, [Docker Hub](https://hub.docker.com/) provides a ton of free Docker images for most use-cases, upon which you can create your own images. | |||
| If your project doesn’t already contain a Dockerfile, don’t worry! Apify offers [many base images](/sdk/js/docs/guides/docker-images) that are optimized for building and running Actors on the platform, which can be found on [Docker Hub](https://hub.docker.com/u/apify). When using a language for which Apify doesn't provide a base image, [Docker Hub](https://hub.docker.com/) provides a ton of free Docker images for most use-cases, upon which you can create your own images. | |||
There was a problem hiding this comment.
double space "found on Docker Hub"
| @@ -1,13 +1,11 @@ | |||
| --- | |||
| title: Deploying | |||
| description: Push local code to the platform, or create a new Actor on the console and integrate it with a Git repo to optionally automatically rebuild any new changes. | |||
| title: How to deploy your Actor | |||
There was a problem hiding this comment.
Do we have a pattern of naming articles with "how to"? I'm not 100% sure, but I'd keep the general approach of "ing ", so in this case, Deploying your Actor, and similarly the others.
There was a problem hiding this comment.
This is special case as the article for input schema is named same as the one in platform docs. You can see context for the change in this discussion. But after changing one, it felt way out of place so it made sense to me to rename the whole section with similar style for consistency. This is temporary solution until Apify Platform section is dealt with
There was a problem hiding this comment.
imho naming articles "how to" is okay. see
There was a problem hiding this comment.
I'm aware of the conversation and I know what how-tos are. The conversation is about the fact that there were three pages called "Input schema". That is, of course, wrong. JC's idea was to rename it to "how to X", and I completely understand why. But we're not here to write articles that have limited context. Our articles must fit our system. While we do have a couple of articles named "How to", it's a deviation, not the norm. The norm (at Apify Docs) is to use the gerund to name articles. It also looks ugly and is hard to navigate if you have a wall of How to X in a page tree.
I'm also not against Diataxis. I think it's right... for Technical Writers. But it is inherently wrong to force users think about what type of educational/documentation material it is before they can find it, let alone open it. It's the same when governmental clerks want you to follow the process even though it doesn't make any sense to you. That's what forcing Diataxis upon users is. Looking at the linked LangChain docs, as a new potential user, I want to see some inspiration or I have some scenario in my mind. But this way, everything is collapsed under multiple sections of "Tutorials", "How-to guides", and "Conceptual guides", which tells me literally nothing, and I have to open all of them to understand what I'll find. If they named the sections "Some articles", "Another batch of articles", "Miscellaneous", it would give me the same amount of information.
That's why I'm pushing for not being named as "How to X". Even if it's a temporary change, it can have a proper naming.
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
Rename to avoid confusion & make titles more action-oriented