diff --git a/docs/user/explanation/documentation-structure.rst b/docs/user/explanation/documentation-structure.rst new file mode 100644 index 00000000000..9393592124e --- /dev/null +++ b/docs/user/explanation/documentation-structure.rst @@ -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. + +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 +--------------------------- + +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. + +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 `_ 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. diff --git a/docs/user/index.rst b/docs/user/index.rst index 833d53b2b54..0cf87dcc091 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -18,6 +18,7 @@ Read the Docs: Documentation Simplified :caption: 💡 Explanation /choosing-a-site + /explanation/documentation-structure /integrations /downloadable-documentation /environment-variables