Skip to main content

Docs conventions

  • Write in English.
  • One topic per page. Link instead of pasting a second copy.
  • Prefer a Mermaid diagram for a flow that has more than two actors.
  • Use tables for ports, env names, and alert names.
  • File names are kebab-case. The first page in a section sets sidebar_position.
  • A service change updates that service's folder. Use the service template.
  • A decision that is hard to reverse gets an ADR.
  • Do not paste secrets, access logs that contain tokens, or contents of .env, .p8, or OAuth client JSON files.
  • Commands are the ones in the repo (manage.sh, Gradle tasks). Do not invent a flag.
  • If the code and an older README disagree, document the code and mention the stale README in one sentence.

Front matter​

---
sidebar_position: 3
---

Add title only when the sidebar label should differ from the H1.

Use root docs links (/docs/architecture/system-context) from pages that move, and relative links (./api) inside a service folder. The site build fails on a broken link.

Build​

npm ci
npm run secret-scan
npm run build

Node 22 (see .nvmrc).