Skip to content

Commit

Permalink
Docs: Methodology section (#10417)
Browse files Browse the repository at this point in the history
* Scissor out methodology and best practice sections

* Small edits to structure

---------

Co-authored-by: Eric Holscher <[email protected]>
  • Loading branch information
benjaoming and ericholscher authored Aug 15, 2023
1 parent 2c6a064 commit a23bc26
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 0 deletions.
50 changes: 50 additions & 0 deletions docs/user/explanation/documentation-structure.rst
Original file line number Diff line number Diff line change
@@ -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.
37 changes: 37 additions & 0 deletions docs/user/explanation/methodology.rst
Original file line number Diff line number Diff line change
@@ -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
5 changes: 5 additions & 0 deletions docs/user/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit a23bc26

Please sign in to comment.