diff --git a/docs/user/explanation/documentation-structure.rst b/docs/user/explanation/documentation-structure.rst new file mode 100644 index 00000000000..63fe12972cb --- /dev/null +++ b/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 ` 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 `_ for this. +* Find a :doc:`example project ` 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 `_. + +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. diff --git a/docs/user/explanation/methodology.rst b/docs/user/explanation/methodology.rst new file mode 100644 index 00000000000..b8a8930fc5d --- /dev/null +++ b/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 `__ + 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 ` + We introduce the Diátaxis methodology which is also used for the documentation you are now reading. + +⏩️ :doc:`Creating 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 ` + 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/index.rst b/docs/user/index.rst index e73a99df621..5be7ee165e6 100644 --- a/docs/user/index.rst +++ b/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