Maintaining the docs

The working rule is short: a change to the product changes its page in the same pull request. A stale page misleads the people who read it and the agents that answer from it, so docs are kept true as part of the change, not afterwards.

Where things live#

Nothing in docs/_authoring/ is published. No page links to it.

Who reads the published site#

• People: hosts, partners, participants and developers.
• The dashboard. It links to the site’s home page, to the Dutch home page, and to two pages directly (see “Pages that must not move”).
• Agents connected over MCP. Their documentation tools read the published site: they fetch llms.txt and then the markdown twin of each page it lists. A page that is not listed there is invisible to them.

So a wrong sentence does not stay on one page. An agent repeats it as a confident answer.

The rule, step by step#

1. Classify the change. Anything a user can observe needs its page updated: an interface label, a route, a permission, a tier, an endpoint, a limit. A change to how the code is built belongs on the pages in this section. “No docs impact” is a valid conclusion. Say so in the pull request.
2. Find the pages. Look three ways: by feature (docs/features/ holds one page per feature), by audience (each folder under docs/users/ retells features for one kind of reader), and by text (search docs/ for the exact labels and names your change touches).
3. Update the feature page first, then the audience pages.
4. Ground every claim in code. Read the code, not the pull request description. Copy interface labels exactly from the source. If you cannot verify something, leave it out.
5. Check the links and open the pull request with the code change.

Rules for a page are in STYLE.md. The ones that break the site when you forget them:

• Every page starts with frontmatter: title, description, audience.
• Links are relative links to .md files.
• folder2website finds pages by following links from docs/README.md. A page that nothing links to does not appear on the site. When you add a page, link it from its section index and from docs/map.md, and add it to docs/sidebar.json. A page missing from that file is left out of the sidebar.
• A translation is a twin file next to the page, named <page>.nl-NL.md.

Pages that must not move#

The product and the repository link to these addresses. Renaming or moving one breaks a link someone clicks.

How the site is built and published#

The site is built from docs/ with folder2website. There is one site per environment, so each site describes the product that environment runs.

What this means for you:

• A merged docs change shows on the staging site first. It reaches docs.dembrane.com with the next release, together with the product change it describes.
• A fix to the pages alone does not have to wait for a release. A maintainer can run the workflow by hand to publish a chosen ref to production. That publishes everything docs/ says at that ref, so check that it describes nothing unreleased.
• The build needs the full git history, because folder2website reads each page’s history for its dates.
• The site is built with the address it will be served at. The MCP documentation tools depend on that address in llms.txt.

The exact build command and the pinned version of the builder are in .github/workflows/docs.yml. To preview the site on your machine, run ./docs/build.sh --serve.

When a page is found to be wrong#

Fix the page. Then find the change that made it stale and check the other pages that change should have touched.

Related#

• Internal developer overview
• Deployment and releases
• Chat and the assistant
• MCP and agent access
• Contributing