kopia lustrzana https://github.com/wagtail/wagtail
rodzic
044206db0d
commit
9217193513
|
@ -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/>`__
|
|
@ -43,4 +43,3 @@ Index
|
|||
editor_manual/index
|
||||
contributing/index
|
||||
releases/index
|
||||
documentation-modes
|
Ładowanie…
Reference in New Issue