Information should have a permanent home as documentation.
Elements that are work in progress can live in the forge on issues or in hedgedoc, but these are not permanent locations.
#. Choose high-level location:
Here is a list of permanent locations:
* The WordPress website: for visitors
* The archive web-app: for visitors and users (of the interface or API)
* The Sphinx docs:
**devel* for contributors
**sysadm* for sys-admins
**users* for users of the infrastructure and all the different services
#. For contributors documentation in devel:
#. Choose if the subject is a high level (cross-module) section or in a specific module
* if the document is relative to only one module, go and add it in the /docs directory in the module
* for cross-module documentation, use the swh-docs repository and the appropriate sub-directory (e.g architecture)
#. Decide if a subsection is needed with multiple pages (tutorials, how-tos, reference or explanation).
#. For sys-admin (in sysadm folder) and user documentation (in users folder):
#. Verify if an existing section is already describing the theme that you want to document.
#. Decide if a subsection is needed with multiple pages (tutorials, how-tos, reference or explanation).
Step 3: Choose the type of documentation
----------------------------------------
We are following Divio's approach with four major types of documentation:
* Tutorial: allowing newcomers to get started and ease the onboarding contributors and users
* How to guide: show how to solve a specific problem in a step-by-step manner. The how to guide is practical to use.
* Reference: theoretical/technical knowledge which is information oriented.
* Explanation: theoretical knowledge which is understanding oriented to analyze, discuss and explain different decisions, including background and context.
For more information:
https://documentation.divio.com/
And Daniele Procida presentation on:
https://www.youtube.com/watch?v=t4vKPhjcMZg
..note::
We propose using in the following naming scheme depending on the type of document:
* Tutorial: Tutorial name]
* How to ...
* Reference: [Reference name]
* Explanation: [Explanation name]
Step 4: Create a page or sub-section with multiple pages