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

[benjaoming]

Successor of #9745

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

Acceptance criteria: All documentation content is correctly categorized in Explanation, How-to and Reference, according to Diátaxis. This means moving pages, splitting up pages and writing new content. This also merges all Business Features into Explanation and How-to. Removes everything from Features that isn't a feature, and combines Features with Advanced Features.

Outcome: Features is a list of old feature files without any purely Explanation/Reference/How-To left. RTD for Business and Advanced Features are gone from the sidebar. About RTD is mostly untouched. To avoid scope creep, we are not changing sub-levels of How-to guides but keeping the old ones - new How-to guides can be added casually in those existing levels since it will change in the next iteration.

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.

• Relabel "Choosing Between Our Two Platforms" to Explanation Docs: Move "Choosing between our two platforms" to Explanation (Diátaxis) #9784
• Relabel "Subprojects" in Explanation (Title suggestion: "Combining many projects in one: Subprojects") Docs: Split Subprojects in Explanation and How-to (Diátaxis) #9785
• Relabel "Localization of Documentation" in Explanation (Title suggestion: "Localization (Translation): Considerations and workflows") Docs: Relabel Localization as Explanation (Diátaxis) #9790
• Relabel "Read the Docs for Science" in Explanation (Title suggestion: "Using documentation in Science and Academic Publishing") Docs: Relabel the "Science" page as Explanation #9832
• Relabel "Build process" in Explanation (Title suggestion: "Build process overview") (@ericholscher)
  • Implement inputs from @agjohnson Docs: update builds and build customization page #9575
• Relabel "Single Version Documentation" to Explanation (same title?) Docs: Relabel "Single version documentation" documentation from feature to explanation (Diátaxis) #9835
• Relabel "Connecting Your VCS Account" in Explanation (Title suggestion: "Integration and authentication through git platforms") Docs: Relabel and move explanation and how-tos around OAuth (Diátaxis) #9834
• Relabel "Organizations" to Explanation (no new title suggested for now, but remember that it's a Business feature) Docs: Relabel Organizations as Explanation (Diátaxis) #9836
• Relabel "Automatic Redirects" to Explanation (no new title suggested for now, is this a member or business feature?) Docs: Relabel Automatic Redirects as "Incoming links: Best practices and redirects" (Diátaxis) #9896
• Relabel "Server Side Search" to Explanation / Fast Server Side Search. Most likely, Search: API V3 #9625 is covering the remaining parts. Docs: Relabel Server Side Search #9897
• Relabel "Technical Documentation Search Engine Optimization (SEO) Guide" from How-to Guides to Explanation Docs: Relabel SEO guide as explanation (Diátaxis) #10004
• Relabel "Connecting Your VCS Account" to "How to connect your user account with GitHub, GitLab and Bitbucket (and?)" in How-to Docs: Relabel and move explanation and how-tos around OAuth (Diátaxis) #9834
• Relabel "Frequently Asked Questions" to How-to (note that the section is intended to be converted into how-tos and ultimately deleted) Docs: Move and update FAQ (Diátaxis) #9908
• Relabel "Build troubleshooting" to "Troubleshooting builds" in How-to Docs: Add new section "How-to / Troubleshooting" and move 2 existing troubleshooting pages #9914
• Relabel "My Build is Using Too Many Resources" to "Troubleshooting slow builds" in How-to Docs: Add new section "How-to / Troubleshooting" and move 2 existing troubleshooting pages #9914
• Relabel "Feature Flags" to Reference (candidate for later deletion, no worries here) Docs: Move Main Features and Feature Flags to "Reference/Features" (Diátaxis) #9915
• Relabel "Policy for Abandoned Projects" to "Abandoned Projects Policy" and move to Reference Docs: Relabel pages to new top-level "Reference/Policies and legal documents" (Diátaxis) #9916

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.

• Split "Flyout Menu"
  • Explanation / Anatomy of the Read the Docs “Flyout” Menu
  • 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 "Status Badges" Docs: Relabel badges as feature reference (Diátaxis) #9951
  • Explanation / Clearly indicate your efforts with a Status Badge
  • How-to / How to add a badge
• Split "Configuration File" Docs: Configuration file pages as explanation and reference (Diátaxis) #9921
  • 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"
  • 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 "Environment Variables" Docs: Refactor "Environment variables" into 3 articles (Diátaxis) #9966
  • Explanation / Build environments and secrets
  • Reference / Environment Variables
• Split "Reproducible Builds" (@ericholscher)
  • Explanation / Reproducible Builds
  • How-to / How to write a requirements.txt for Reproducible Builds
• Split "Custom Domains"
  • Start from Docs: Split Custom Domains as Explanation and How-to Guide (Diátaxis) #9676
  • Explanation / Custom Domains
  • How-to / How to set a custom domain
• Split "Downloadable Documentation"
  • Explanation / Offline Formats
  • How-to / How to generate PDF and ePub (Sphinx)
  • Rename to "offline formats" and close Docs: update downloadable documentation page #9577
  • PR: Docs: Refactor downloadable docs #9768
• Split "Documentation Hosting Features" Docs: Relabel and reorganize hosting features as reference (Diátaxis) #9952
  • Explanation / Serving content and built-in features
  • How-to / How to set a custom 404
  • How-to / How to create a custom robots.txt
  • There might be more how-tos that can be spun-off from existing explanation contents - open issues or write new how-tos?
• Split "Canonical URLs"
  • Explanation / Canonical URLs: Effectively archiving old versions
  • How-to / How to use Canonical URLs
  • Work will happen in this PR: Docs: Split Custom Domains as Explanation and How-to Guide (Diátaxis) #9676
• Split "Project Privacy Level" and "Secret links and password protected documentation" Docs: Refactor all business features into feature reference + change "privacy level" page (Diátaxis) #10007
  • Explanation / Private projects
  • Explanation / Secret links and password protected documentation
  • How-to / How to make a project private and share it
• Split "Build Notifications and Webhooks"
  • 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 build notification
• Split "VCS Integrations"
  • Start from Docs: Split and relabel VCS integration as explanation and how-to (Diátaxis) #9675
  • Explanation / Connecting git repositories
  • How-to / How to connect your Git repository
• Split "Preview Documentation from Pull Requests"
  • Explanation / Preview Documentation from Pull Requests
  • How-to / How to configure pull request builds
  • Start from Docs: Split up Pull Request Builds into a how-to guide and reference (Diátaxis) #9679
  • Observe and implement inputs from Docs: update pull request page #9574
• Split "Single Sign-On"
  • Explanation / Single Sign-On for organizations
  • How-to / How to setup Single Sign-On (SSO) for your organization
  • PR: Docs: Split SSO docs into HowTo/Explanation (Diátaxis) #9801
• Split "Automation Rules" Docs: Split "Automation rules" into reference and how-to (Diátaxis) #9953
  • Explanation / Automation Rules
  • How-to / How to create new versions automatically
• Split "User-defined Redirects" Docs: Relabel Automatic Redirects as "Incoming links: Best practices and redirects" (Diátaxis) #9896
  • Explanation / User-defined Redirects
  • How-to / How to create redirect rules
• Split "Traffic Analytics"
  • Start from Docs: Split Traffic Analytics to a How-to guide and a Feature entry (Diátaxis) #9677
  • Explanation / Traffic Analytics
  • How-to / How to enable and disable Google Analytics
  • How-to / How to understand your users’ interaction with your documentation (Just noting
    that this article is scoped for ITERATION 4!)
• Split "Security Log" Docs: Refactor security logs as reference (Diátaxis) #9985
  • Explanation / Security Logging
  • How-to / How to enable and use Security Logs

New

An entirely new article is created

• None

Remove

• Remove "Google Summer of Code" - "Don't need it in the menu. Perhaps mark it :orphan:, or just link it from some deprecated content page?" Docs: Make the GSOC page orphaned (Diátaxis) #9949

Wrapping up

• "Advanced Features" and "Read the Docs for Business" should be empty and removed. "Features" should also be empty and removed, but ff there are articles left here, we need to deal with them by adding new tasks/issues. Make note of "None" actions that simply place an article under Features without any further changes. Docs: Navigation menu wrap-up: About, Features and Advanced Features as Reference (Diátaxis) #10010
  • Versioned Documentation

Iteration 1.5 - "Put a bow on it"

• Do an SEO audit on H1's of all pages
• Refactor the index page to highlight our fancy new docs
• Ship it on latest & stable!! 🎉

[ericholscher]

I'd like to see us moving faster here. A proposal to discuss in our call tomorrow:

• Benjamin to try to get 1 draft PR refactor up per day (checking off at least 1 item on the iteration)
• Eric to try to do a "v2" of an incoming draft PR each day. Basically do an edit & copy iteration instead of a bunch of GH comments, so things don't get blocked on review as long

Does that make sense to try out for a sprint and see if we can get a faster cadence going?