As multiple people were working with writing documentation for different personas, the directory structure underneath each persona started diverging. This made it harder for someone to easily jump between work on different personas and easily locate documents and orient themselves.
sourcefolder MUST be the root for all docs.
For each top-level persona that we have, there MUST be a separate folder whose name closely matches the name of the persona (no caps, underscores instead of spaces).
Course Operators -> course_ops
Software Developers -> developers
Each persona folder MUST contain a folder for each documentation type (
Each folder MUST have an
index.rstfile that is the root document for that folder.
The index.rst file MUST contain a
toc_treethat connects all content in that folder and sub-folders.
Visually this would look something like:
persona ├── concepts │ ├── index.rst │ └── some-concept.rst ├── how-tos │ ├── index.rst │ └── how-to-something.rst ├── quickstarts │ └── index.rst ├── references │ └── index.rst └── index.rst
Having a consistent layout should make it easier for documentors to be able to navigate the repository and quickly switch between personas and know where to put new documentation and where to find the roots for each sub-area of a persona.