Documentation¶
The rule¶
Documentation travels with the code (constitution, Principle VII). Every change that alters behavior, configuration, the Management API, the backoffice UI, the data schema or install/upgrade steps updates this documentation in the same pull request. A change is not finished until the documentation reflects it.
Where does my change go?¶
| Change type | Section to update |
|---|---|
| Install, upgrade or prerequisite change | Getting Started / Upgrading |
| Configuration setting added/changed/removed | Configuration |
| Backoffice UI change | Backoffice Guide |
| Licensing rule or behavior (validation, expiry, binding) | Licensing Concepts |
| Management API, architecture, data/schema, conventions | Developer Guide |
| Any user-visible change | Changelog (Unreleased) |
No docs impact¶
If a change has no user- or developer-visible impact (for example an internal refactor or a test-only change), check No docs impact in the pull request template and add a one-line reason.
Keep the public site safe¶
This site is public
The documentation is published publicly. Never include secrets, signing or private
keys, credentials, customer data, real license keys, or internal hostnames and
connection strings. Use obviously fake example values, such as
XXXX-XXXX-EXAMPLE or licensing.example.com.
Preview and build locally¶
Set up once (requires Python 3.12 or later):
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r docs/requirements.txt
Preview with live reload at http://127.0.0.1:8000:
mkdocs serve
Run the same strict build as the pull request check. It fails on broken links, broken anchors and pages missing from the navigation:
mkdocs build --strict
Add a page¶
- Create the Markdown file in the right section folder under
docs/. - Add it to
navinmkdocs.yml; pages that are not in the navigation fail the strict build. - Run
mkdocs build --strictand fix every warning.