Revert "Writing documentation in for modes"

This reverts commit 044206db0d.
pull/6768/head
Matt Westcott 2021-02-04 11:51:36 +00:00
rodzic 044206db0d
commit 9217193513
2 zmienionych plików z 0 dodań i 72 usunięć

Wyświetl plik

@ -1,71 +0,0 @@
Documentation in four modes of information delivery
===================================================
.. rst-class:: intro
Wagtail documentation is written in four modes of information delivery.
Each type of information delivery has a purpose and targets a specific audience.
* :ref:`doc-style-tutorial`, learning-oriented
* :ref:`doc-style-how-to-guide`, goal-oriented
* :ref:`doc-style-reference`, information-oriented
* :ref:`doc-style-explanation`, understanding-oriented
Credits `Daniele Procida: What nobody tells you about documentation <https://www.divio.com/blog/documentation/>`__.
Write in style
--------------
Each page of the Wagtail documentation should be written in **one** mode of information delivery.
Mixing types of information delivery on a single page is bad style.
These pages are are confusing to read, and harder to understand.
It is best to split documents that mix the types of information delivery.
Add links to the first section of each document to cross reference the same topic.
Writing documentation in a specific mode will help our users to understand, and quickly find what they are looking for.
.. _doc-style-tutorial:
Tutorial
--------
Tutorials are designed to be a **learning-oriented** resource that take
newcomers by the hand and guide them through a specific topic. To facilitate effective
learning, tutorials provide examples to illustrate the subjects they cover.
They may not necessarily follow best-practices by the letter. They are
designed to make it easier to get started.
`More about tutorials <https://documentation.divio.com/tutorials/>`__
.. _doc-style-how-to-guide:
How-to guide
------------
A guide offer advice on how best to achieve a given task. How-to guides are **goal-oriented**.
`More about how-to guides <https://documentation.divio.com/how-to-guides/>`__
.. _doc-style-reference:
Reference
---------
A reference is well structured and allows the reader to find information about a specific
topic. They should be short and to the point. Reference material is **information-oriented**.
`More about reference <https://documentation.divio.com/reference/>`__
.. _doc-style-explanation:
Explanation
-----------
Explanation is high-level and explains concepts and design decisions.
There little, or no code involved. Background information is **understanding-oriented**.
`More about explanation <https://documentation.divio.com/explanation/>`__

Wyświetl plik

@ -43,4 +43,3 @@ Index
editor_manual/index
contributing/index
releases/index
documentation-modes