General improvements to our docs

[humitos]

I received a lot of good feedback at Write the Docs Vilnius that we may want to consider and take care of it to improve our docs.

• Hard to find what they need in the docs
  • Titles could be improved with better keywords and less repetitive
  • Toctree from index contains irrelevant content for this page
  • Full toctree could be shown in a separate page
  • Consider the usage of Control + F on a page
• Showing documentation for deprecated features/things at the same level that the one that it's currently recommended is confusing (Config V1 and V2)
• There are some docs pages with duplicated content (versions, builds and build environment, etc)
• Guides should be split in How-To and Troubleshooting
• Always make acronyms expand (on hover, for example)
• The landing page of the docs could be re-structured depending on the type of user reading: a first comer should not be lost into "Developer Documentation"
• "About Read the Docs" should be placed at the bottom of the page
• Revisit titles to communicate better. For example, change "Versions" to "Versioning your documentation"
• There are features listed that are not really a feature that the user needs to know a lot about them from the landing page: Webhooks, for example. Since Read the Docs manages this automatically when importing a project, this page could be listed under Troubleshooting (when looking for a problem) or Developer Documentation when trying to create a manual/generic Webhook.

Related to #5675 and #5676

[davidfischer]

This is great and thanks for starting this!

Some of these are implemented in #5819 but there's still more work to be done. The ones in #5819 are:

* Full toctree could be shown in a separate page
* Toctree from index contains irrelevant content for this page
* "About Read the Docs" should be placed at the bottom of the page
* The landing page of the docs could be re-structured depending on the type of user reading: a first comer should not be lost into "Developer Documentation"

Guides should be split in How-To and Troubleshooting

I would further say to break down the guides page into logical groupings like guides for sphinx, guides for RTD itself.

Always make acronyms expand (on hover, for example)

Sphinx has a feature for this.

[ericholscher]

I crossed out the issues we fixed in the main issue description 👍

[ericholscher]

Showing documentation for deprecated features/things at the same level that the one that it's currently recommended is confusing (Config V1 and V2)

Should we remove Config v1 from the TOC, similar to API v1?

[humitos]

Should we remove Config v1 from the TOC, similar to API v1?

I think that's the way to go. Remove them from the first sight but make them available if you look closer for them.

[tapaswenipathak]

Hi folks: Can I work on the ticket or is the ticket internal?

[stsewd]

@tapaswenipathak sure

[humitos]

I found this article very helpful to organize all our docs in a structured manner that seems easy to follow as a whole (team/community) since it divides the type of page/document/article in four:

• tutorials
• how-to guides
• explanation
• technical reference

which seems to be a good pattern to follow and I think it fit with what we already have (type of pages), but better structured.

[tapaswenipathak]

Appreciate your thoughts @humitos, taking on my head and splitting the docs as per you described.

[humitos]

We refactored our documentation a lot from when this issue was opened. I'm closing it.