Docs: Methodology section

docs/user/explanation/documentation-structure.rst

@@ -0,0 +1,50 @@
+How to structure your 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 defined structure,
+readers either won't find information that they need or get frustrated on the way.
+
+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.
+
+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.
+
+.. _diataxis:
+
+Diátaxis Methodology
+--------------------
+
+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 it in the `official Diátaxis documentation <https://diataxis.fr/>`_.
+
+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.

docs/user/explanation/methodology.rst

@@ -0,0 +1,37 @@
+Methodology and best practice
+=============================
+
+In this section,
+we are covering important methods and best practices that will make your documentation better.
+
+.. seealso::
+
+    `Write the Docs: Topic Archive <https://www.writethedocs.org/topics/>`__
+        A collection of conference talks and articles,
+        indexed by topic (eg. ``Metrics and analytics`` or ``Information architecture``)
+
+You can familiarize yourself with these topics before or after writing documentation.
+We encourage that you read this at any time,
+as this content is applicable to many stages of the documentation process.
+
+⏩️ :doc:`The Diátaxis Methodology <documentation-structure>`
+    We introduce the Diátaxis methodology which is also used for the documentation you are now reading.
+
+⏩️ :doc:`Creating reproducible builds </guides/reproducible-builds>`
+    Every documentation project has dependencies that are required to build it.
+    Using an unspecified versions of these dependencies means that your project can start breaking.
+    In this guide,
+    learn how to protect your project against breaking randomly.
+    **This is one of our most popular guides!**
+
+⏩️ :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

docs/user/index.rst

@@ -20,7 +20,12 @@ Read the Docs: documentation simplified
 
    /choosing-a-site
    /integrations
+   /downloadable-documentation
+   /environment-variables
+   /subprojects
+   /localization
    /explanation/advanced
+   /explanation/methodology
 
 .. toctree::
    :maxdepth: 2