Skip to content

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

  1. Create the Markdown file in the right section folder under docs/.
  2. Add it to nav in mkdocs.yml; pages that are not in the navigation fail the strict build.
  3. Run mkdocs build --strict and fix every warning.