Skip to content

Documentation Guidelines

Generated artifact. Do not edit manually.

Generated by: scripts/build_compendia.py Regenerate with: python3 scripts/build_compendia.py --compendium dev-handbook --web-and-tex Source of truth: docs/dev/source/

Language / Sprache: English (EN) · Deutsch (DE) | PDF: English PDF · Deutsches PDF

Compendium: §1 Documentation Guidelines · §2 Landscape JSON Reference · §3 Minimal Schema & Fallback · §4 Authoring Editors · §5 Graph Editor · §6 Flashcard Editor · §7 Node Ordering · §8 Liquibase · §9 Auto-Update (SSE)

1. Documentation Guidelines

Every documentation file in docs/ has one primary role so durable concepts, QA rules, generated status snapshots, and dated dossiers stay cleanly separated.

1.1. Document Roles and Placement Rules

| Role | Purpose | Canonical Location | Source of Truth? | | –- | –- | –- | –- | | Concept | Durable domain model, semantics, and architecture | docs/concept/ | Yes | | Runbook | Repeatable operational command steps | Near the owning process doc | Yes | | Process | Review rules, status meanings, and decision gates | docs/qa-ci/ or docs/dev/ | Yes | | Generated status | Computed report, queue, or dashboard snapshot | docs/qa-ci/status/ | No | | Pilot or dossier | Dated investigation, PoC, or one-off audit record | docs/qa-ci/archive/ or docs/dev/ | No (unless stated) | | Implementation note | Developer-facing schema, tool, or migration detail | docs/dev/ (tmp/ for throwaway work) | Sometimes | {cols="20%,34%,28%,18%"}

1.2. Bilingual Single-Source Compendia (docs/compendia.json)

Durable reference handbooks are authored as bilingual (de/en) single-source compendia compiled by scripts/doc_compendium/ and build_compendia.py into MkDocs Web Markdown pages and typeset LuaLaTeX PDFs. Never mix languages in one file and never hand-edit generated Web pages; edit source/chapters/*.{de,en}.md with 1:1 AST block parity, identical {#sec:...} / anchors="...", @ref{sec:...}, canonical repo:... links, and pure ASCII code blocks (<= 72 chars/line). Contract-pinned deployment/freeze records, dated workboards, and generated status reports remain standalone Markdown files.

| Compendium ID | Canonical source/ | Tracking Policy | Generated PDFs (DE / EN) | | –- | –- | –- | –- | | skill-graph | docs/concept/skill-graph/source/ | untracked | skillpilot-graph-definition.{pdf,en.pdf} | | skill-graph-architecture | docs/concept/skill-graph/architecture-source/ | committed-web | skillpilot-skill-graph-architecture.{de,en}.pdf | | whitepaper | docs/whitepaper/source/ | committed-web (+ DE PDF) | whitepaper.{de,en}.pdf | | glossary | docs/concept/glossary/source/ | committed-web | skillpilot-glossary.{de,en}.pdf | | didactic | docs/concept/didactic/source/ | committed-web | skillpilot-didactics-and-planning.{de,en}.pdf | | runtime-workflows | docs/concept/runtime-workflows/source/ | committed-web | skillpilot-coach-and-runtime-architecture.{de,en}.pdf | | production-pipelines | docs/production-pipelines/source/ | committed-web | skillpilot-production-pipelines.{de,en}.pdf | | qa-ci | docs/qa-ci/source/ | committed-web | skillpilot-curriculum-quality-handbook.{de,en}.pdf | | qa-ci-lanes | docs/qa-ci/lanes-source/ | committed-web | skillpilot-qa-lanes-and-release-contracts.{de,en}.pdf | | security | docs/security/source/ | committed-web | skillpilot-security-and-privacy.{de,en}.pdf | | dev-handbook | docs/dev/source/ | committed-web | skillpilot-developer-and-editor-guide.{de,en}.pdf | {cols="22%,32%,18%,28%" longtable=true}

python3 scripts/build_compendia.py --web-and-tex
python3 scripts/build_compendia.py --pdfs
python3 scripts/build_compendia.py --check-committed-web
python3 scripts/build_compendia.py --check-untracked-outputs

1.3. MkDocs [ DE | EN ] Switcher, Generated Notices, Templates, and Checks

  • Site navigation & [ DE | EN ] pill switcher: mkdocs.yml (site_url: https://enpasos.github.io/skillpilot/) pairs Compendium (EN) / Kompendium (DE) nav groups and registers standalone pairs under standaloneBilingualPairs in docs/compendia.json. language-switcher.js + bilingual-map.js toggle active-language pages while keeping monolingual operational/dated pages visible in both modes. Unlisted dated dossiers and docs/qa-ci/status/ reports remain reachable via section index.md files.
  • Generated notices & templates: Generated Markdown files declare Generated by, Regenerate with, and Source of truth headers registered in generatedMarkdownNoticeRegistry.ts (npm run check:generated-doc-notices, npm run check:generated-status-registry). Durable QA lane docs follow Purpose / Source Of Truth / Generated Artifacts / Run / Blocking Semantics / Review Ledger / Review Workflow / Expansion Criteria / Related Documents; runbooks follow Run The Audit / Inspect Results / Decide Or Fix An Item / Interpret Diagnostics / Verify Local Changes; PoC/archive records carry ISO dates in filenames.
  • Terminology, outside-docs/ links, and CI checks: Core vocabulary follows the Glossary and checkTerminology.ts (npm run check:terminology). Links leaving docs/ must use GitHub https://github.com/enpasos/skillpilot/blob/main/... (or /tree/main/...) URLs so published site pages never 404, verified by .github/workflows/docs_checks.yml:
git diff --check
cd app
npm run check:terminology
npm run check:docs-links
npm run check:docs-indexes