Documentation Conventions

How documentation is organized across the punkt portal. Every repository that contributes docs follows these rules (they’re also mirrored in each repo’s CLAUDE.md).

The invariant

If it lives in docs/modules/, it is published documentation. Everything else — process logs, plans, brainstorming — lives elsewhere in the repo.

What belongs (publish)

Category	Contents
Overview	What the project is and who it’s for.
Usage	Install, configure, use, troubleshoot (user-facing).
Reference	API, CLI, configuration, data models.
Architecture & Decisions	Design overviews and Architecture Decision Records (ADRs).
Operations	Deployment, runbooks, backup / DR.
Contributing	Dev setup, build, test, release.

What does NOT belong

Keep these in the repo but out of docs/modules/ — put them in a repo-level notes/ folder (or docs/superpowers/, which is excluded):

AI/agent process artifacts — nightly & morning reports, devlogs, backlogs, sprint-status, autonomous-run logs, handovers, implementation-artifacts, market-research scratch, dated status reports.
Planning / brainstorming scratch.

The test: "Will a teammate deliberately look this up in three months?"
Yes → docs/. A log, plan, or status an agent emitted while working → notes/.

Per-repo layout

docs/
  antora.yml                 # component: name, title, version, start_page, nav
  modules/
    ROOT/
      nav.adoc               # left navigation (xref links, grouped by .Section)
      pages/*.adoc           # the pages — AsciiDoc, one "= Title" each
      images/                # image::name[]
      attachments/           # downloads
notes/                       # NOT published — process/AI artifacts, plans

Products (versioned) publish versions from git tags; everything else rolls on the default branch (versionless).

Authoring

Write AsciiDoc (.adoc), not Markdown. Exactly one level-0 = Title per page.
New page → add the .adoc under pages/ and an * Title line in nav.adoc.
Link within a component with other.adoc; across components with component::page.adoc.

Internationalization (i18n)

Multilingual sites use the language-as-version pattern: each language is a component version, and the portal’s version dropdown becomes a language switcher.

docs/
  de/  antora.yml (version: de, display_version: Deutsch)          + modules/ROOT/...
  en/  antora.yml (version: en, display_version: English,
                   prerelease: true)                               + modules/ROOT/...

The playbook lists one source per language (start_path: docs/de, docs/en).
prerelease: true on the non-default language makes the other the default ("latest") — e.g. Eventsanitäter is German-first, so English is the prerelease.
Translate a page by creating it (same filename) under every language’s pages/ and adding it to each nav.adoc; stub untranslated pages with a link to the other language (English version).