Refactor documentation navigation (#11139)

ericholscher · agjohnson · web-flow · commit 2ac31e1921d5 · 2024-02-23T06:32:35.000-08:00
* Refactor documentation navigation

This is an initial proof of concept of a concept-based TOC,
instead of using Diataxis.

This shows a lot more where we're missing various pieces of content,
and overall I think really improves our documentation structure.

A big benefit downstream of this is making our page titles more explicit,
so users know what each page has on it.
I've started doing this very lightly so you can get a sense,
but it makes things way more clear.

* Make hidden :)

* Some smaller copy changes

* More futzing

* A bit more futzing

* Remove security section for now

* Update docs/user/index.rst

Co-authored-by: Anthony &lt;aj@ohess.org&gt;

* A bit more futzing with where things live

* Small guide fixes

---------

Co-authored-by: Anthony &lt;aj@ohess.org&gt;
diff --git a/docs/user/about/index.rst b/docs/user/about/index.rst
@@ -64,11 +64,11 @@ we've brought most of the most important ones below.
 .. toctree::
    :hidden:
 
-   /commercial/index
    /reference/policies
    /advertising/index
    /story
    /sponsors
+   /science
    /open-source-philosophy
    /team
    /support
diff --git a/docs/user/api/index.rst b/docs/user/api/index.rst
@@ -1,11 +1,8 @@
-Public API
-==========
-
-This section of the documentation details the public API
-usable to get details of projects, builds, versions and other details
-from Read the Docs.
-
+Public REST API
+===============
 
+This section of the documentation details the public REST API.
+Useful to get details of projects, builds, versions, and other resources.
 
 .. toctree::
    :maxdepth: 3
diff --git a/docs/user/build-notifications.rst b/docs/user/build-notifications.rst
@@ -1,5 +1,5 @@
-Build notifications via webhooks and email
-==========================================
+Build failure notifications
+===========================
 
 Build notifications can alert you when your documentation builds fail so you can take immediate action.
 We offer the following methods for being notified:
diff --git a/docs/user/commercial/index.rst b/docs/user/commercial/index.rst
@@ -1,5 +1,5 @@
-About |com_brand|
-=================
+Business hosting
+================
 
 .. this page is currently moving towards becoming "About Read the Docs for Business"
 .. rather than an index of features.
diff --git a/docs/user/commercial/organizations.rst b/docs/user/commercial/organizations.rst
@@ -1,5 +1,5 @@
-Organizations: permissions for projects and teams
--------------------------------------------------
+Organizations
+-------------
 
 .. include:: /shared/admonition-rtd-business.rst
 
diff --git a/docs/user/commercial/privacy-level.rst b/docs/user/commercial/privacy-level.rst
@@ -1,3 +1,7 @@
+.. TODO: This is a super weird page..
+
+:orphan:
+
 Project privacy level
 ---------------------
 
diff --git a/docs/user/commercial/sharing.rst b/docs/user/commercial/sharing.rst
@@ -1,4 +1,4 @@
-Private documentation sharing
+Sharing private documentation
 =============================
 
 .. include:: /shared/admonition-rtd-business.rst
diff --git a/docs/user/commercial/single-sign-on.rst b/docs/user/commercial/single-sign-on.rst
@@ -1,5 +1,5 @@
-Choosing a Single Sign-On (SSO) approach for your organization
-==============================================================
+Single Sign-On (SSO)
+====================
 
 .. include:: /shared/admonition-rtd-business.rst
 
diff --git a/docs/user/commercial/subscriptions.rst b/docs/user/commercial/subscriptions.rst
@@ -1,5 +1,5 @@
-How to manage your Read the Docs for Business subscription
-==========================================================
+How to manage your subscription
+===============================
 
 We want to make it easy to manage your billing information.
 All :doc:`organization owners </commercial/subscriptions>` can manage the subscription for that organization.
diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst
@@ -1,4 +1,4 @@
-Configuration file tutorial
+Configuration file overview
 ===========================
 
 As part of the initial set up for your Read the Docs site,
diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst
@@ -1,5 +1,5 @@
-Configuration file v2 (.readthedocs.yaml)
-=========================================
+Configuration file reference
+============================
 
 Read the Docs supports configuring your documentation builds with a configuration file.
 This file is named ``.readthedocs.yaml`` and should be placed in the top level of your Git repository.
diff --git a/docs/user/downloadable-documentation.rst b/docs/user/downloadable-documentation.rst
@@ -1,5 +1,5 @@
-Understanding offline formats
-=============================
+Offline formats (PDF, ePub, HTML)
+=================================
 
 This page will provide an overview of a core Read the Docs feature: building docs in multiple formats.
 
diff --git a/docs/user/environment-variables.rst b/docs/user/environment-variables.rst
@@ -1,7 +1,7 @@
 .. _Environment Variables:
 
-Understanding environment variables
-===================================
+Environment variable overview
+=============================
 
 Read the Docs allows you to define your own environment variables to be used in the build process.
 It also defines a set of :doc:`default environment variables </reference/environment-variables>` with information about your build.
diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Deep dive into Read the Docs
 ============================
 
@@ -18,13 +20,3 @@ we explain some of the more specific or advanced concepts of writing documentati
 
 ⏩️ :doc:`/explanation/configuration-file`
   Some background on our configuration file and versioning configuration files.
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-
-   /subprojects
-   /localization
-   /downloadable-documentation
-   /environment-variables
-   configuration-file
diff --git a/docs/user/explanation/configuration-file.rst b/docs/user/explanation/configuration-file.rst
@@ -1,5 +1,9 @@
-Versioning configuration files
-==============================
+.. TODO: This is another place where I'd love to share this content with users, but it's not quite there yet.
+
+:orphan:
+
+Why keep configuration files in Git
+===================================
 
 Content and structure of documentation undergo big and small changes.
 And eventually, the configuration of a documentation project also changes.
diff --git a/docs/user/explanation/index.rst b/docs/user/explanation/index.rst
@@ -22,15 +22,3 @@ Explanation
 
 ⏩️ :doc:`/environment-variables`
   An introduction to how pre-defined and user-defined environment variables work and how to use them.
-
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   /choosing-a-site
-   /integrations
-   /subprojects
-   /localization
-   /downloadable-documentation
-   /environment-variables
diff --git a/docs/user/explanation/methodology.rst b/docs/user/explanation/methodology.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Methodology and best practice
 =============================
 
@@ -27,11 +29,3 @@ as this content is applicable to many stages of the documentation process.
 ⏩️ :doc:`Search engine optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>`
     This article explains how documentation can be optimized to appear in search results,
     increasing traffic to your docs.
-
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-
-   documentation-structure
-   /guides/best-practice/index
diff --git a/docs/user/flyout-menu.rst b/docs/user/flyout-menu.rst
@@ -1,3 +1,5 @@
+.. TODO: Update the images to the new flyout design, and update to include Addons
+
 Flyout menu
 ===========
 
diff --git a/docs/user/guides/canonical-urls.rst b/docs/user/guides/canonical-urls.rst
@@ -17,7 +17,7 @@ you have to ensure that the value is correct.
 This can be complex,
 supporting pull request builds (which are published on a separate domain),
 special branches
-or if you are using :term:`subproject` s or :ref:`translations <localization:Localization of Documentation>`.
+or if you are using :term:`subproject` s or :doc:`translations </localization>`.
 We recommend not including a ``html_baseurl`` in your ``conf.py``,
 and letting Read the Docs define it.
 
diff --git a/docs/user/guides/embedding-content.rst b/docs/user/guides/embedding-content.rst
@@ -1,3 +1,5 @@
+.. TODO: Write feature page for hoverxref
+
 How to embed content from your documentation
 ============================================
 
diff --git a/docs/user/guides/index.rst b/docs/user/guides/index.rst
@@ -7,11 +7,13 @@ These guides will help walk you through specific use cases
 related to Read the Docs itself, documentation tools like Sphinx and MkDocs
 and how to write successful documentation.
 
-.. tip::
-   We recommend looking through the list,
-   maybe there is a guide you hadn't looked for?
-
 .. toctree::
-   :glob:
 
-   */index
+   Project setup and configuration </guides/setup/index>
+   Build process </guides/build/index>
+   Upgrading and maintaining projects </guides/maintenance/index>
+   Content, themes and SEO </guides/content/index>
+   Security and access </guides/access/index>
+   Account management </guides/management/index>
+   Best practice </guides/best-practice/index>
+   Troubleshooting problems </guides/troubleshooting/index>
diff --git a/docs/user/guides/manage-read-the-docs-teams.rst b/docs/user/guides/manage-read-the-docs-teams.rst
@@ -1,3 +1,5 @@
+.. TODO: We should documentation how community team management works
+
 How to manage Read the Docs teams
 =================================
 
diff --git a/docs/user/guides/setup/index.rst b/docs/user/guides/setup/index.rst
@@ -43,7 +43,6 @@ The following how-to guides help you solve common tasks and challenges in the se
 
 
 .. toctree::
-   :maxdepth: 1
    :hidden:
 
    Connecting your Read the Docs account to your Git provider </guides/connecting-git-account>
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -4,34 +4,93 @@ Read the Docs: documentation simplified
 .. toctree::
    :maxdepth: 2
    :hidden:
-   :caption: 🚀 Tutorials
+   :caption: Getting started
 
    /tutorial/index
+   /choosing-a-site
    /intro/getting-started-with-sphinx
    /intro/getting-started-with-mkdocs
    /intro/import-guide
-   /config-file/index
    /examples
 
 .. toctree::
    :maxdepth: 2
    :hidden:
-   :caption: 💡 Explanation
+   :caption: Project setup and configuration
 
-   /choosing-a-site
-   /integrations
-   /downloadable-documentation
+   /config-file/index
+   /config-file/v2
+   /automation-rules
+   /guides/reproducible-builds
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Build process
+
+   /builds
+   /build-customization
+   /reference/git-integration
+   /pull-requests
+   /build-notifications
    /environment-variables
+   /reference/environment-variables
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Hosting documentation
+
+   /versions
    /subprojects
    /localization
-   /explanation/advanced
-   /explanation/methodology
+   /versioning-schemes
+   /custom-domains
+   /canonical-urls
+   /reference/cdn
+   /reference/sitemaps
+   /reference/404-not-found
+   /reference/robots
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Reading documentation
+
+   /downloadable-documentation
+   /guides/embedding-content
+   /server-side-search/index
+   /server-side-search/syntax
+   /flyout-menu
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Maintaining projects
+
+   /user-defined-redirects
+   /reference/analytics
+   /security-log
+   /badges
+   /explanation/documentation-structure
+   /guides/best-practice/links
    /security-implications
 
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Business features
+
+   /commercial/index
+   /commercial/organizations
+   /commercial/single-sign-on
+   /commercial/sharing
+   /commercial/subscriptions
+
 .. toctree::
    :maxdepth: 2
    :hidden:
-   :caption: 🪄 How-to guides
+   :caption: How-to guides
 
    Project setup and configuration </guides/setup/index>
    Build process </guides/build/index>
@@ -45,15 +104,10 @@ Read the Docs: documentation simplified
 .. toctree::
    :maxdepth: 2
    :hidden:
-   :caption: 📚 Reference
+   :caption: Reference
 
-   /reference/features
-   /config-file/v2
-   /builds
-   /build-customization
-   /server-side-search/syntax
-   /faq
    /api/index
+   /faq
    /changelog
    /about/index
    Developer Documentation <https://dev.readthedocs.io>
diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst
@@ -1,12 +1,14 @@
+.. TODO: This page could be a great overview of our build philosophy, but it's not quite there yet.
+
+:orphan:
+
 ..
    Some points we want to cover in this article:
    * Talk about the benefits of always up to date docs
    * Discuss versioning in here, since it relies directly on Git?
    * Have a small diagram that shows (You --push--> GitHub --webhook--> RTD --Build docs--> Deploy
        (Perhaps reuse this: https://about.readthedocs.com/images/homepage.png)
 
-
-
 Continuous Documentation Deployment
 ===================================
 
diff --git a/docs/user/localization.rst b/docs/user/localization.rst
@@ -1,5 +1,5 @@
-Localization of documentation
-=============================
+Localization and Internationalization
+======================================
 
 In this article, we explain high-level approaches to internationalizing and localizing your documentation.
 
diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst
@@ -1,5 +1,5 @@
-Preview documentation from pull requests
-========================================
+Pull request previews
+=====================
 
 Your project can be configured to build and host documentation for every new
 pull request. Previewing changes during review makes it
diff --git a/docs/user/reference/analytics.rst b/docs/user/reference/analytics.rst
@@ -1,3 +1,5 @@
+.. TODO: Break these our into separate pages, and combine with Guides for fuller content
+
 Analytics for search and traffic
 ================================
 
diff --git a/docs/user/reference/environment-variables.rst b/docs/user/reference/environment-variables.rst
diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst
diff --git a/docs/user/reference/git-integration.rst b/docs/user/reference/git-integration.rst
diff --git a/docs/user/security-implications.rst b/docs/user/security-implications.rst
diff --git a/docs/user/subprojects.rst b/docs/user/subprojects.rst
diff --git a/docs/user/user-defined-redirects.rst b/docs/user/user-defined-redirects.rst
diff --git a/docs/user/versioning-schemes.rst b/docs/user/versioning-schemes.rst
diff --git a/docs/user/versions.rst b/docs/user/versions.rst

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Private documentation sharing`
	`1`	`+Sharing private documentation`
`2`	`2`	`=============================`
`3`	`3`
`4`	`4`	`.. include:: /shared/admonition-rtd-business.rst`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Configuration file tutorial`
	`1`	`+Configuration file overview`
`2`	`2`	`===========================`
`3`	`3`
`4`	`4`	`As part of the initial set up for your Read the Docs site,`