Promote and restructure guides

[astrojuanlu]

See discussion at #8321. After extensive discussion, I approached this with several goals in mind:

• Reordering the guides in a more meaningful way,
• removing the sphinx/community/commercial separation,
• studying what guides should be feature content, and
• trying to minimize the changes to the index page.

And, in addition, I had some non-goals:

• Rewrite or update the guides (we will have time for that in the future),
• Evolve the visual aspect of our documentation (see POC guides landing redesign with Sphinx-design extension #8513 for some ideas around that),
• Address how we use the toctree (see DO NOT MERGE: Make toctrees visible #8523 for a draft attempt).

I ended up doing these four things:

1. Move some guides that were clearly "feature documentation" to the "getting started" section.
2. Replace the Tools/Community/Commercial categories by Authors/Administrators/Developers.
3. Reorder the guides according to (present) popularity.
4. Present guides in the index in a similar fashion as we do with the rest of our documentation.

I think these categories make it more explicit what is the audience of each document, although there are some grey areas of course.

Also, for the index, I picked the most popular guides, and for the rest, I added an "others" link to not overwhelm (more) the readers.

[astrojuanlu]

Rendered result: https://docs--8528.org.readthedocs.build/en/8528/#how-to-guides

[ericholscher]

This is a 💯 refactor. I love this structure of the guides -- much more intuitive and valuable.

I would like to perhaps use this as an opportunity to clean up some of the titles on the pages, if possible. I see you already did a couple, but I think there's a lot more room here to clarify them (and make them better for SEO).

I'd also love to figure out a core set of features that we care about, and promote/document effectively. I feel like we're slowly getting to that point, but we should really discuss and have it defined somewhere (and very obviously highlighted on the website/marketing pages/docs).

A couple questions for moving forward:

• How do we distinguish .com content? Perhaps an emoji and a warning at the top of the guide or similar to what we do for sphinx-only content?
• I feel like the First steps & Getting started sections are a bit muddled (especially since the first steps contain getting started docs). I think we can work to clean this up a bit. Perhaps rename Getting started section to Platform Overview or Feature Documentation or Primary Features? We already have Advanced Features, so maybe it makes sense to differentiate it from that?

[ericholscher]

This is a much better way to think about the guide structure 💯

[ericholscher]

This shows we need more of these guides 🤔

[astrojuanlu]

Double yes: we need more guides, and some of the current ones should probably be moved to Sphinx...

[astrojuanlu]

Thanks for the thorough feedback @ericholscher . On your questions:

How do we distinguish .com content? Perhaps an emoji and a warning at the top of the guide or similar to what we do for sphinx-only content?

I was precisely thinking of an emoji. And rather than a warning, a custom-colored admonition?

I feel like the First steps & Getting started sections are a bit muddled (especially since the first steps contain getting started docs). I think we can work to clean this up a bit. Perhaps rename Getting started section to Platform Overview or Feature Documentation or Primary Features? We already have Advanced Features, so maybe it makes sense to differentiate it from that?

Totally agree. Will review this now.

[astrojuanlu]

Opened #8535 about the first part. Hope to tackle that in a future iteration.

[astrojuanlu]

I'm done with the first round of review - @ericholscher I see that you approved, but I have made some significant changes since, so I'm asking for another review just in case.

[ericholscher]

Looks great -- really excited for the docs to keep improving 💯

[ericholscher]

👍 Matching the UI is a good place to start. I could see moving to something like:

Suggested change

	Traffic Analytics
	Traffic Analytics - See top performing doc pages

In the future, but we'd need to change up how we're linking to them. Perhaps adding a subhead of some kind would be another way to handle this.

[astrojuanlu]

Thanks a lot! Opened #8537 to focus on SEO.

[humitos]

I'm late on this PR, but I'd like to suggest getting rid of | as separator of the links because it's almost impossible to read them, IMO. Also, it makes super hard to start reading the first word, realize that it's not the guide you are looking for and jump to the next link because there is almost no visual difference between where a link ends and a new one starts.

Now that we have just a few links in this section, can't we just use bullets for them:

[astrojuanlu]

I agree that the vertical separators are not very nice, and I think we have discussed about removing them.

However, a stated non-goal of this PR was to not "Evolve the visual aspect of our documentation", so I kept consistency to what we have now to avoid derailing the discussion. @nienn proposed some cool ideas in #8513, but I think we first need to think through the structure of all our docs. As @ericholscher said above,

I'd also love to figure out a core set of features that we care about, and promote/document effectively. I feel like we're slowly getting to that point, but we should really discuss and have it defined somewhere (and very obviously highlighted on the website/marketing pages/docs).