mirror
/
wagtail
kopia lustrzana https://github.com/wagtail/wagtail
1
0
Forkuj 0
Kod Zgłoszenia Packages Projekty Wydania Wiki Aktywność
wagtail/docs/contributing/documentation_modes.rst

112 wiersze
3.9 KiB
ReStructuredText
Czysty Zwykły widok Historia

Explain how we write documentation
2021-02-04 11:46:14 +00:00
Writing documentation
=====================
.. 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.
Fix documentation indentation Fix code block indentation in tutorial.rst Prevent it from being displayed as a quote. Fix indentation in pages.rst Fix indentation in indexing.rst Fix indentation in searching.rst Fix indentation in backends.rst Fix indentation in renditions.rst Fix indentation in custom_image_model.rst Fix indentation in feature_detection.rst Fix indentation in image_serve_view.rst Fix indentation in custom_document_model.rst Fix indentation in i18n.rst Fix indentation in privacy.rst Fix indentation in page_editing_interface.rst Fix indentation in rich_text_internals.rst Fix indentation in extending_hallo.rst Fix indentation in configuration.rst Fix indentation in usage.rst Fix indentation in theory.rst Fix indentation in model_reference.rst Fix indentation in queryset_reference.rst Configure editors to indent .rst files with 2 spaces In order for the documentation to be styled correctly, the generator depends on indentation. Too much indentation can result in the content being wrapped in a quote block, which looks bad. Fix indentation in sitemaps.rst Fix indentation in frontendcache.rst Fix indentation in routablepage.rst Fix indentation in table_block.rst Fix routablepage.rst autodocs disppearing Fix indentation in table_block.rst Fix indentation in redirects.rst Fix indentation in table_documentation-modes.rst Fix indentation in browser_issues.rst Fix indentation in release_process.rst Fix indentation of release notes One more indent fix in the release notes Fix indentation warnings Fix warning about undefined label in docs Error during `make html`: wagtail/docs/releases/1.7.rst:25: WARNING: undefined label: jpeg_image_quality
2021-02-05 11:02:05 +00:00
* :ref:`doc-mode-tutorial`, learning-oriented
* :ref:`doc-mode-how-to-guide`, goal-oriented
* :ref:`doc-mode-reference`, information-oriented
* :ref:`doc-mode-explanation`, understanding-oriented
Explain how we write documentation
2021-02-04 11:46:14 +00:00
Update links to Diátaxis framework Information about the documentation system is now maintained and updated at https://diataxis.fr.
2021-04-12 12:45:40 +00:00
We are following Daniele Procida's `Diátaxis documentation framework <https://diataxis.fr/>`__.
Explain how we write documentation
2021-02-04 11:46:14 +00:00
.. _choose-a-writing-mode:
Choose a writing mode
---------------------
Each page of the Wagtail documentation should be written in single mode of information delivery.
Single pages with mixed modes are harder to understand.
If you have documents that mix the types of information delivery,
it’s best to split them up. Add links to the first section of each document to cross reference other documents on the same topic.
Writing documentation in a specific mode will help our users to understand and quickly find what they are looking for.
.. _doc-mode-tutorial:
Tutorial
--------
Tutorials are designed to be **learning-oriented** resources which guide newcomers through a specific topic. To help effective learning, tutorials should provide examples to illustrate the subjects they cover.
Tutorials may not necessarily follow best practices. They are designed to make it easier to get started. A tutorial is concrete and particular. It must be repeatable, instil confidence, and should result in success, every time, for every learner.
Do
~~
- Use conversational language
- Use contractions, speak in the first person plural,
be reassuring. For example: “We’re going to do this.”
- Use pictures or concrete outputs of code to reassure people that they’re on the right track.
For example: “Your new login page should look like this:” or “Your directory should now have three files”.
Don’t
~~~~~
- Tell people what they’re going to learn.
Instead, tell them what tasks they’re going to complete.
- Use optionality in a tutorial. The word ‘if’ is a sign of danger!
For example: “If you want to do this…”
The expected actions and outcomes should be unambiguous.
- Assume that learners have a prior understanding of the subject.
Update links to Diátaxis framework Information about the documentation system is now maintained and updated at https://diataxis.fr.
2021-04-12 12:45:40 +00:00
`More about tutorials <https://diataxis.fr/tutorials/>`__
Explain how we write documentation
2021-02-04 11:46:14 +00:00
.. _doc-mode-how-to-guide:
How-to guide
------------
A guide offers advice on how best to achieve a given task.
How-to guides are **task-oriented** with a clear **goal or objective**.
Do
~~
- Name the guide well - ensure that the learner understands what exactly the guide does.
- Focus on actions and outcomes. For example: “If you do X, Y should happen.”
- Assume that the learner has a basic understanding of the general concepts
- Point the reader to additional resources
Don’t
~~~~~
- Use an unnecessarily strict tone of voice. For example: “You must absolutely NOT do X.”
Update links to Diátaxis framework Information about the documentation system is now maintained and updated at https://diataxis.fr.
2021-04-12 12:45:40 +00:00
`More about how-to guides <https://diataxis.fr/how-to-guides/>`__
Explain how we write documentation
2021-02-04 11:46:14 +00:00
.. _doc-mode-reference:
Reference
---------
Reference material is **information-oriented**.
A reference is well-structured and allows the reader to find information about a specific topic.
They should be short and to the point. Boring is fine! Use an imperative voice.
For example: “Inherit from the Page model”.
Most references will be auto-generated based on doc-strings in the Python code.
Update links to Diátaxis framework Information about the documentation system is now maintained and updated at https://diataxis.fr.
2021-04-12 12:45:40 +00:00
`More about reference <https://diataxis.fr/reference/>`__
Explain how we write documentation
2021-02-04 11:46:14 +00:00
.. _doc-mode-explanation:
Explanation
-----------
Explanations are **understanding-oriented**.
They are high-level and offer context to concepts and design decisions.
There is little or no code involved in explanations,
which are used to deepen the theoretical understanding of a practical draft.
Explanations are used to establish connections and may require some prior knowledge of the principles being explored.
Update links to Diátaxis framework Information about the documentation system is now maintained and updated at https://diataxis.fr.
2021-04-12 12:45:40 +00:00
`More about explanation <https://diataxis.fr/explanation/>`__