readthedocs · ericholscher · Feb 22, 2023 · benjaoming · Feb 23, 2023 · benjaoming
@@ -0,0 +1,43 @@
+How to structure your documentation
+===================================
+
+Structuring your documentation is an important part of the authoring process.
+It's important to think about the reader of the documentation,
+since they are the primary user of documentation.
-Structuring your documentation is an important part of the authoring process.
-It's important to think about the reader of the documentation,
-since they are the primary user of documentation.
+A documentation project's ultimate goal is to be read and understood by a reader.
+Readers need to be able to :term:`discover <discoverability>` the information that they need.
+Without an intuitive structure,
+readers either won't find information that they need or get frustrated on the way.
+
+Having a structure in mind can happen from the very beginning of a documentation project.
+Changing and adapting your structure is often also necessary.
+
+.. tip::
+
+   Even if your documentation already has a structure,
+   we invite you to keep reading.
+   Changing a documentation structure is hard work,
+   but the rewards are big.
-Structuring your documentation is an important part of the authoring process.
-It's important to think about the reader of the documentation,
-since they are the primary user of documentation.
+A documentation project's ultimate goal is to be read and understood by a reader.
+Readers need to be able to :term:`discover <discoverability>` the information that they need.
+Without an intuitive structure,
+readers either won't find information that they need or get frustrated on the way.
+
+Having a structure in mind can happen from the very beginning of a documentation project.
+Changing and adapting your structure is often also necessary.
+
+.. tip::
+
+   Even if your documentation already has a structure,
+   we invite you to keep reading.
+   Changing a documentation structure is hard work,
+   but the rewards are big.
+
+One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation.
+Starting with a blank page is often the hardest part of documentation,
+so anything we can do to remove this problem is a win.
+
+Recommendations for process
+---------------------------
-Recommendations for process
---------------------------
+Choosing a structure
+--------------------
+
+Good news!
+You don't have to invent all of the structure yourself,
+since a lot of experience-based work has been done to come up with a universal documentation structure.
-Recommendations for process
---------------------------
+Choosing a structure
+--------------------
+
+Good news!
+You don't have to invent all of the structure yourself,
+since a lot of experience-based work has been done to come up with a universal documentation structure.
+
+In order to avoid starting with a blank page,
+we recommend a simple process:
+
+* Choose a structure for your documentation. We recommend `Diátaxis <https://diataxis.fr/>`_ for this.
+* Find a :doc:`example project </examples>` or template to start from.
+* Start writing by filling in the structure.
+
+This process helps you get started quickly,
+and helps keep things consistent for the reader of your documentation.
+
+Diátaxis
+--------
+
+The documentation you're reading is written using the Diátaxis framework.
+It has four major parts as summarized by this image:
+
+.. image:: https://diataxis.fr/_images/diataxis.png
+
+We recommend that you read more about Diátaxis in the `documentation <https://diataxis.fr/>`_ for it.
+
+Explaining the structure to your users
+-------------------------------------
+
+One of the benefits of Diátaxis is that it's a well-known structure,
+and users might already be familiar with it.
+As long as you stick to the structure,
+your users should be able to use existing experience to navigate.
+
+Using the names that are defined (eg. Tutorials, Explanation) in a user-facing way also helps here.
@@ -18,6 +18,7 @@ Read the Docs: Documentation Simplified
    :caption: 💡 Explanation
 
    /choosing-a-site
+   /explanation/documentation-structure
    /integrations
    /downloadable-documentation
    /environment-variables