Docs: Diátaxis refactor - iteration 2 high-level tracking

[benjaoming]

Successor of #9746

This is a high-level issue moved from the initial planning document. Further issues may be opened and linked from here.

• Acceptance Criteria: New sub-levels are created in Explanation and How-to, old How-to sub-levels are removed, Any remaining “Features” are moved to Reference and finally delete “Features”. Out of scope: Articles that have to be created from scratch.

• Outcome: The menu already starts to have clear entrypoints aligned with Diátaxis (but it is still lengthy).

Ongoing work from iteration 1

• Relabel "Build process" in Explanation (Title suggestion: "Build process overview") (@ericholscher)
  • Implement inputs from @agjohnson Docs: update builds and build customization page #9575
  • Docs: Refactor the build & build customization pages (Diátaxis) #10028
• Split "Flyout Menu" We can skip this, a new flyout menu is on its way
  • Reference / Features / Flyout Menu - https://docs.readthedocs.io/en/stable/flyout-menu.html
  • How-to / How to customize Read the Docs “Flyout” Menu
    • Example: https://stackoverflow.com/questions/50425740/how-to-find-the-pdf-version-of-a-read-the-docs-project
• Split "Configuration File" Docs: Configuration file pages as explanation and reference (Diátaxis) #10416
  • Explanation / Configuration File: Using “Configuration as Code” (.readthedocs.yaml)
  • Reference / Configuration File
  • Bonus: Post an issue that we should perhaps have a How-to for adding a configuration file to a project?
• Split "Build customization" Docs: Refactor the build & build customization pages (Diátaxis) #10028
  • Discussed on call: Let's focus on reference
  • Explanation / Build process details
  • How-to / How to override the entire default build process (Docsify, Pelican, Hugo and more)
  • It's possible that this will generate more how-to articles.
  • Implement inputs from @agjohnson Docs: update builds and build customization page #9575
• Split "Reproducible Builds" (@ericholscher) Docs: Refactor Reproducible Builds page (Diátaxis) #10030
  • Explanation / Reproducible Builds
  • How-to / How to write a requirements.txt for Reproducible Builds
• Split "Build Notifications and Webhooks" Docs: Split email notifications and webhook notifications into separate howtos #10396
  • Discussed on call: Let's focus on reference
  • Reference / features / Build Notifications and Webhooks
  • Reference / features / Preview Preview Documentation from Pull Requests
  • How-to / How to setup a [Slack,Discord] build notification
  • Actual screenshots on build notifications No space, already plenty of illustrations here.

Before everything else

About creating new sub-levels: A sub-level contains a stub index.rst with a TOC. The TOC can refer to any other page in the Sphinx project, but make sure to remove that page from other TOCs.

• Fix the mixup of Title Case and Sentence case. Docs: Use "Sentence case" for titles #10055
• Create follow-up tasks from Docs: Navigation reorder (Diátaxis) #10026 Docs: emojis in TOC captions, FontAwesome on external links in TOC (Diátaxis) #10039
• Updates to style guide around build terminology: Steps, jobs, commands etc. Docs: Style guide stash #10250
• Updates to style guide for consistency around what to call the "Config File" Docs: Style guide stash #10250
• Add all new sub-levels in Explanation Docs: New Explanation sub-levels + high-level introduction as explanation (Diátaxis) #10071
  • See initial planning document for title suggestions
  • Write introductions and create a nice menu using description lists and emojis
• Add all new sub-levels in How-to guides Docs: New how-to sublevels (Diátaxis) #10131
  • See initial planning document for title suggestions
  • Write introductions and create a nice menu using description lists and emojis
• Add all new sub-levels in Reference
  • Resolve suggestion to also have a combined level Reference => API (containing Platform API and Search API)
  • Move all existing pages to their destination sub-level. Some pages do not have sub-levels. Do not rename anything. See initial planning document.

Glossary update

• Add more common terms to the glossary and apply them where they are needed. Common words: "reproducible", "docs", "pinning" Docs: New entries to glossary #10249
• Ensure we're no longer saying "VCS" anywhere that can just read "Git".

Relabel

Existing contents are moved with light changes to title and content. Intentionally not called “move” because we don’t change URLs and break stuff, we just relabel it.

• We want to figure out a better sublevel title for "How-to / Content, themes and SEO"
• Re: Docs: New how-to sublevels (Diátaxis) #10131 (comment)
  • How-to / "Connecting an automatically imported Git repository" Docs: Relabel howto guides for Git repository configuration (Diátaxis) #10247
  • How-to / "Connecting a manually imported Git repository" Docs: Relabel howto guides for Git repository configuration (Diátaxis) #10247
  • Reuse warning from https://docs.readthedocs.io/en/latest/guides/importing-private-repositories.html on other

Split

Existing article is split up and some new contents are added to shape the new results. Every Split action has at least 2 destinations.

• Empty

Improve

• Needs some general updating: https://docs.readthedocs.io/en/latest/guides/importing-private-repositories.html Docs: Update "How to import private repositories" (Diátaxis) #10251
• Main index page rough update Docs: Changes to main index page (Diátaxis) #10186
• Research solutions and enablers for page meta data Docs: Research solution for reusable page meta data #10157
• Open issue with discussion around the next iteration on the main index page Docs: Main page next steps #10252

New

• New article from "Choosing between our two platforms", title draft: "Choosing a dedicated documentation platform". Docs: New Explanation sub-levels + high-level introduction as explanation (Diátaxis) #10071
• Feature page about Git Integration Docs: Add "Git provider account connection" feature description #10442

Remove

• Remove "Read the Docs for Business" - analyze if certain contents might live elsewhere.

After everything else

• "All How-to Guides - Index page" is created as the last sub-level in How-to Guides.
• old How-to sub-levels are removed, Any remaining “Features” are moved to Reference and finally delete “Features”
• About Read the Docs is removed (if it wasn't already removed) It doesn't make sense to remove right now

[benjaoming]

Dumping some notes from the sentence-case refactor... will order them as tasks later in this or other iterations... or not at all:

• We should use refactor our docs to use menuselection in a lot of cases where we use guilabel.
• A lot of places could benefit from tabs:: to show alternative instructions for GitHub/Bitbucket or Sphinx/MkDocs etc.
• We write our features with lower-case generally. For instance "server side search" is a feature, but it's not a Proper Noun. We haven't named features as such.
• Exceptions for APIs? Public API, Embed API, Server Side Search API?
• Sphinx-specific guides should use a convention: "How to do X (Sphinx)"
• We should generally write "documentation" rather than "docs".
• "Read the Docs for Community" => "Read the Docs Community" (or just use org_brand)
• Go through all :orphan: pages?
• Privacy Policy is widely used as a proper noun, I didn't change that, but I did change the title of the page to "Privacy policy" and I think since it's just a privacy policy, we don't need to call it by a proper noun. Otherwise, we can call soooo many generic things by Proper Nouns.... our Platform, our Documentation etc.
• "Configuration file" not "Configuration File" or "Config File".

[benjaoming]

A lot of guides have Troubleshooting nested inside the guide, while some other troubleshooting items are separate. I'm wondering if this should be changed so all Troubleshooting is lodged next to its how-to guide, rather than in separate sections.

[ericholscher]

We should generally write "documentation" rather than "docs".

Kinda goes against our brand, though? Not sold on this one.

Sphinx-specific guides should use a convention: "How to do X (Sphinx)"

I think you just want in Sphinx. Using any other convention feels weird to a reader or Googler.

We should use refactor our docs to use menuselection in a lot of cases where we use guilabel.

Seems quite low priority, FWIW. Only if we do another full doc review, or just in the normal work of updating content.

"Read the Docs for Community" => "Read the Docs Community" (or just use org_brand)

Yea, I thought that's what we were doing already?

"Configuration file" not "Configuration File" or "Config File".

Again, I'm not 100% sold that the longer version is better here. Config is pretty commonly used, but worth a discussion.

A lot of guides have Troubleshooting nested inside the guide, while some other troubleshooting items are separate. I'm wondering if this should be changed so all Troubleshooting is lodged next to its how-to guide, rather than in separate sections.

This seems reasonable for small troubleshooting suggestions. Breaking them out is almost certainly going to make a worse experience for the user.

I do think we have some troubleshooting-only content though, like our existing troubleshooting pages. Those seems guide-level.

[benjaoming]

• Found an occurrence in config file v2 "Our build servers run Ubuntu 18.04, with the default set of package repositories installed. We don't currently support PPA's or other custom repositories."

[agjohnson]

We should generally write "documentation" rather than "docs".

Kinda goes against our brand, though? Not sold on this one.

I'm +1 on documentation generally, docs is a bit jargony or at least shorthand, and it has overlap with "docs" authored from Word/Google Docs/etc or "legal docs".

[ericholscher]

We should generally write "documentation" rather than "docs".

Kinda goes against our brand, though? Not sold on this one.

I'm +1 on documentation generally, docs is a bit jargony or at least shorthand, and it has overlap with "docs" authored from Word/Google Docs/etc or "legal docs".

Good point. Makes sense for a general rule to use documentation I guess.

[benjaoming]

Note to add something in our style guide about using explicit labels rather than headlines, the refactor shows that it's harder to improve headlines when they are also used in references that break. We probably want to tweak more headlines.

[benjaoming]

Open PRs should be referenced here.

These are the items that don't have PRs open now:

• Split "Flyout Menu" - this one seems possible to work on but pretty low priority given that a whole new client is coming up. See current docs: https://docs.readthedocs.io/en/stable/flyout-menu.html
• We want to figure out a better sublevel title for "How-to / Content, themes and SEO": I don't have any new ideas for this level. I know the title is a bit incoherent, but I like the nouns that it contains using quite few characters. So I'm okay with it.
• How-to / How to setup a [Slack,Discord] build notification - can probably be ignored for now since it's all in a howto already - https://docs.readthedocs.io/en/stable/guides/build-notifications.html
• Actual screenshots on build notifications - a screenshot for https://docs.readthedocs.io/en/stable/build-notifications.html would be much appreciated.
• Reuse warning from https://docs.readthedocs.io/en/latest/guides/importing-private-repositories.html on other pages - seems easy, will do.

[ericholscher]

Going to call this done, as we've finished up the last little bits here. 🎉