Generic guide: improvements about platformsh-docs HOT 2 OPEN

1. Stuck the versions of the stacks in the blogposts (Express, Django...) for not being ping in few months/years that the tutorial is not working

Is the suggestion here that we add explicit notes to the blog posts that say which version was used?

2. @GuGuss like the Django blogpost title (Up(sun) and running with Django) and would like all of our blogpost to have the same "wordplay" --> Up(sun) and running with ...

I leave this to the article authors if they want to match my wordplay title or not.

3. In the stack dedicated section, in the note block, tell the reader that the Upsun demo app link is a call to action, as it is a link to an "external" website (the console) to create a new demo app. Otherwise, being redirected to the console login page can be confusing.

I believe we can add an icon next to the link to remove the jarring effect here.

4. In the stack dedicated section, remove the first link in the Getting started section as the Upsun demo application is already mention in the note block above.

Makes sense, yeah let's remove.

5. In the stack dedicated section, change title of the Documentation to Go further: Getting started is for beginner and then, documentation section is for more advanced user.

I don't understand the suggested change here.

6. Framework section: is it possible to add the same menu as for the generic guide per stacks, and remove the subitem of the Configure your project section that are not language related to the stack?
   example ...

We had a lot of discussion around this structure - I'd like to test for a while before adopting one of the alternatives we had thought about. In the interim, and perhaps to solve the issue here, let's generalize {{< get-started/steps >}} so that it can be included in the Getting started section of each stack page, providing the steps same as we see here https://docs.upsun.com/get-started/here.html

7. make the Framework.language section clickable with a dedicated page to the language, with a hello world example for the language.

This is a larger conversation.

from platformsh-docs.

On #2, are we planning then on removing all stack-specific guides from the documentation and migrate them to the blog? Seems odd to have the docs duplicate the blog, or the blog duplicate the docs.

On #5, this is now no longer documentation. This is a list of links, and does contain documentation on how to "Deploy Express on Upsun". IMO, if we are going to have dedicated stack sections in the documentation, then they need to include information that covers the specifics/uniqueness of a stack that isn't covered by the generic guide. Blog posts should then expand on the documentation to cover a topic that isn't included in the docs (e.g. adding a melisearch service to an express project).

If the intent of these sections is to just be a list of resources, then they should be renamed "<stack/framework> on Upsun" to indicate the page covers topics concerning the stack/framework and its operation on Upsun.

Specific to the Getting Started guide

I find the Errors on First Push section to be confusing. Given the section before it (Required Files) covers the configuration files, we have them run project:init, and commit the configuration files, the Errors on First Push section with an error of Configuration directory '.upsun' not found. should never occur. Even under the Console tab, the error would only occur if an integration has been used (side note, the image at this location is incorrect as well), but we've already stated at the Create Project step that Git Integrations are outside the scope of the guide and are covered later. This section should be moved from this page and into the page covering Git Integrations.

Should we give a clarification for this Warning as to why an environment might not be active? Given we have them create the branch using the Upsun cli, it will by default activate the environment (and we mention this in that section) so this seems out of place.

from platformsh-docs.