-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Scissor out methodology and best practice sections * Small edits to structure --------- Co-authored-by: Eric Holscher <[email protected]>
- Loading branch information
1 parent
2c6a064
commit a23bc26
Showing
3 changed files
with
92 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters