Docs: Changes to main index page (Diátaxis)

docs/user/examples.rst

@@ -39,10 +39,10 @@ Real-life examples
 
 .. image:: _static/images/awesome-list.svg
   :alt: Awesome List badge
-  :target: https://github.com/readthedocs-examples/
+  :target: https://github.com/readthedocs-examples/awesome-read-the-docs
 
 We maintain an **Awesome List** where you can contribute new shiny examples of using Read the Docs.
-Please refer to the instructions on how to submit new entries on `Awesome Read the Docs Projects <https://github.com/readthedocs-examples/>`_.
+Please refer to the instructions on how to submit new entries on `Awesome Read the Docs Projects <https://github.com/readthedocs-examples/awesome-read-the-docs>`__.
 
 
 Contributing an example project

docs/user/guides/cross-referencing-with-sphinx.rst

@@ -1,5 +1,5 @@
-Cross-referencing with Sphinx
-=============================
+How to use cross-references with Sphinx
+=======================================
 
 When writing documentation you often need to link to other pages of your documentation,
 other sections of the current page, or sections from other pages.

docs/user/index.rst

@@ -67,20 +67,20 @@ by building, versioning, and hosting of your docs, automatically.
 This enables many "docs like code" workflows,
 keeping your code & documentation as close as possible.
 
-Never out of sync |:arrows_counterclockwise:|
+|:arrows_counterclockwise:| Never out of sync
     Whenever you push code to your favorite version control system,
     whether that is Git or Mercurial,
     Read the Docs will automatically build your docs
     so your code and documentation are always up-to-date.
     Read more about :doc:`/integrations`.
 
-Multiple versions |:card_index_dividers:|
+|:card_index_dividers:| Multiple versions
     Read the Docs can host and build multiple versions of your docs
     so having a 1.0 version of your docs and a 2.0 version
     of your docs is as easy as having a separate branch or tag in your version control system.
     Read more about :doc:`/versions`.
 
-Open Source and User Focused |:heartbeat:|
+|:heartbeat:| Open Source and User Focused
     Our code is free and `open source <https://github.com/readthedocs/>`_.
     :doc:`Our company </about/index>` is bootstrapped and 100% user focused.
     |org_brand| hosts documentation for over 100,000 large
@@ -92,126 +92,76 @@ Open Source and User Focused |:heartbeat:|
 
 You can find out more about our all the :doc:`features </reference/features>` in these pages.
 
-First steps
------------
-
-Are you new to software documentation?
-Are you looking to use your existing docs with Read the Docs?
-Learn about documentation authoring tools such as Sphinx and MkDocs
-to help you create fantastic documentation for your project.
-
-* **Tutorial**: :doc:`/tutorial/index`
-
-* **Getting started**:
-  :doc:`With Sphinx </intro/getting-started-with-sphinx>` |
-  :doc:`With MkDocs </intro/getting-started-with-mkdocs>` |
-  :doc:`/choosing-a-site`
 
-* **Importing your existing documentation**:
-  :doc:`Import guide </intro/import-guide>`
+First time here?
+----------------
 
-Read the Docs feature overview
-------------------------------
+🚀 :doc:`/tutorial/index`
+  Read to take the first practical steps to getting started on Read the Docs?
 
-Learn more about configuring your automated documentation builds
-and some of the core features of Read the Docs.
+.. TODO: This next item needs its article to be finished in a separate PR
+.. https://github.com/readthedocs/readthedocs.org/pull/10071
 
-* **Overview of core features**:
-  :doc:`/custom-domains` |
-  :doc:`/versions` |
-  :doc:`/downloadable-documentation` |
-  :doc:`/server-side-search/index` |
-  :doc:`/analytics` |
-  :doc:`/pull-requests` |
-  :doc:`/build-notifications` |
-  :doc:`/user-defined-redirects` |
-  :doc:`/security-log`
+💡 :doc:`Why use a dedicated documentation platform? </integrations>`
+  Get an introduction to some of the most important reasons for using a *Documentation CI* and build *docs as code*.
 
-* **Connecting with GitHub, Bitbucket, or GitLab**:
-  :doc:`Connecting your VCS account </connected-accounts>`
+:doc:`🔠 All tutorials </tutorials/index>`
+  Using a documentation tool like Sphinx or MkDocs for the first time or importing an existing project?
+  We have the tutorials to get you started!
 
-* **Read the Docs build process**:
-  :doc:`Configuration reference </config-file/index>` |
-  :doc:`Build process </builds>` |
-  :doc:`Build customization </build-customization>` |
-  :doc:`/environment-variables` |
-  :doc:`/reference/environment-variables` |
-  :doc:`/badges`
 
-* **Troubleshooting**:
-  :doc:`/support` |
-  :doc:`/faq`
+How-to guides
+-------------
 
+🪄 :doc:`/guides/cross-referencing-with-sphinx`
+  Learn how to use cross-references in a Sphinx project
 
-Advanced features of Read the Docs
-----------------------------------
+🪄 :doc:`/analytics`
+  How to use our Traffic analytics to understand how users are interacting with your documentation.
 
-Read the Docs offers many advanced features and options.
-Learn more about these integrations and how you can get the most
-out of your documentation and Read the Docs.
+🪄 :doc:`/guides/pull-requests`
+  Switch on Pull Request builds and enjoy auto-generated previews.
 
-* **Advanced project configuration**:
-  :doc:`subprojects` |
-  :doc:`Single version docs <single-version>` |
-  :doc:`flyout-menu` |
-  :doc:`feature-flags`
+:doc:`🔠 All how-to guides </guides/index>`
+  Have a look at the entire catalog for **many many more how-to guides**.
 
-* **Multi-language documentation**:
-  :doc:`Translations and localization <localization>`
 
-* **Versions**
-  :doc:`Automation rules <automation-rules>`
+Reference
+---------
 
-* **Topic specific guides**:
-  :doc:`How-to guides <guides/index>`
+📚 :doc:`/reference/features`
+  An overview and reference of all features of Read the Docs.
 
-* **Extending Read the Docs**:
-  :doc:`REST API <api/index>`
+📚 :doc:`/config-file/index`
+  Reference for the ``.readthedocs.yaml`` file.
 
+📚 :doc:`/builds`
+  Reference to how builds are processed
 
+📚 :doc:`/build-customization`
+  Reference of the ways that you can add your own build logic or replace the default build steps.
 
-Read the Docs for Business
---------------------------
+📚 :doc:`/server-side-search/syntax`
+  How our search works - available for all documentation projects.
 
-Read the Docs has a commercial offering with improved support and additional features.
+📚 :doc:`/api/index`
+  Building a documentation project on Read the Docs gives access to a number of great APIs that you can take advantage of on your website and integration tools.
 
-* **Read the Docs for Business**:
-  :doc:`Organizations <commercial/organizations>` |
-  :doc:`Single sign on <commercial/single-sign-on>` |
-  :doc:`Project privacy level <commercial/privacy-level>` |
-  :doc:`Sharing externally <commercial/sharing>`
+📚 `Developer documentation <https://dev.readthedocs.io/>`__
+  Do you want to help develop Read the Docs? This is where to get started.
 
 
-The Read the Docs project and organization
-------------------------------------------
-
-Learn about Read the Docs, the project and the company,
-and find out how you can get involved and contribute to the development and success
-of Read the Docs and the larger software documentation ecosystem.
-
-* **Policies & Process**:
-  :doc:`security` |
-  :doc:`DMCA takedown policy <dmca/index>` |
-  :doc:`/abandoned-projects` |
-  :doc:`/unofficial-projects` |
-  :doc:`Release notes & changelog <changelog>`
-
+Explanation
+-----------
 
-* **The people and philosophy behind Read the Docs**:
-  :doc:`About us </about/index>` |
-  :doc:`Team <team>` |
-  :doc:`Open source philosophy <open-source-philosophy>` |
-  :doc:`Our story <story>`
+.. TODO: This next item needs its article to be finished in a separate PR
+.. https://github.com/readthedocs/readthedocs.org/pull/10071
 
-* **Financial and material support**:
-  :doc:`advertising/index` |
-  :doc:`Sponsors <sponsors>`
+💡 :doc:`Continuous Documentation </integrations>`
+  Learn about the many advantages of having your documentation continuously build and deployed.
 
-* **Legal documents**:
-  :doc:`Terms of service <terms-of-service>` |
-  :doc:`Privacy policy <privacy-policy>` |
-  :doc:`Data processing agreement <legal/dpa/index>`
+.. TODO: This next item needs its article to be finished in a separate PR
+.. https://github.com/readthedocs/readthedocs.org/pull/10071
 
-* **Getting involved with Read the Docs**:
-  :doc:`/glossary` |
-  :doc:`Developer documentation <rtd-dev:index>`
+💡 Advanced topics: Deep-dive into Read the Docs
+  Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs.

docs/user/tutorial/index.rst

@@ -673,9 +673,6 @@ and Read the Docs:
 - Whether you are a documentation author, a project administrator, a developer, or a designer,
   you can follow our how-to guides that cover specific tasks,
   available under :doc:`/guides/index`.
-- You can check out some of the
-  :ref:`index:Advanced features of Read the Docs`,
-  like :doc:`/subprojects` or :doc:`/automation-rules`, to name a few.
 - For private project support and other enterprise features,
   you can use :doc:`our commercial service </commercial/index>`
   (and if in doubt, check out :doc:`/choosing-a-site`).

docs/user/tutorials/index.rst

@@ -0,0 +1,41 @@
+.. this page is referenced from the front page but it's unnecessary as a navigation section for now.
+
+:orphan:
+
+=========
+Tutorials
+=========
+
+⏩️ :doc:`/tutorial/index`
+  This is where you should go if you are trying Read the Docs for the first time!
+
+
+⏩️ :doc:`/intro/getting-started-with-sphinx`
+  Sphinx is the most popular documentation tool on our platform.
+  But that's not to say that it's *easy* if you are using it for the first time.
+  We recommend a soft start with this tutorial.
+
+⏩️ :doc:`/intro/getting-started-with-mkdocs`
+  Another great and popular tool is MkDocs.
+  This is especially popular because of its default of using Markdown.
+  This tool is well-supported on our platform and that's why we have a tutorial.
+
+⏩️ :doc:`/intro/import-guide`
+  If you already wrote your documentation,
+  this guide will help you get started at the most natural point:
+  Importing an existing documentation project.
+
+⏩️ :doc:`/examples`
+  If you are bootstrapping a new documentation project,
+  here is a list of example projects that you can derive your setup from.
+
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   /tutorial/index
+   /intro/getting-started-with-sphinx
+   /intro/getting-started-with-mkdocs
+   /intro/import-guide
+   /examples