Skip to content

Dokumentationsrichtlinien

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/

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

Kompendium: §1 Dokumentationsrichtlinien · §2 Landscape-JSON-Referenz · §3 Minimales Schema & Fallback · §4 Autoreneditoren · §5 Graph-Editor · §6 Flashcard-Editor · §7 Knotensortierung · §8 Liquibase · §9 Auto-Update (SSE)

1. Dokumentationsrichtlinien

Jede Dokumentationsdatei unter docs/ besitzt genau eine primäre Rolle, damit dauerhafte Konzepte, QS-Regeln, generierte Statusberichte und datierte Dossiers sauber getrennt bleiben.

1.1. Dokumentrollen und Ablageregeln

| Rolle | Zweck | Typischer Ablageort | Source of Truth? | | –- | –- | –- | –- | | Konzept | Dauerhaftes Domänenmodell, Semantik und Architektur | docs/concept/ | Ja | | Runbook | Wiederholbare operative Befehlsschritte | Nahe beim Prozessdokument | Ja | | Prozess | Review-Regeln, Statusbedeutungen und Entscheidungsgates | docs/qa-ci/ oder docs/dev/ | Ja | | Generierter Status | Berechneter Bericht, Queue oder Dashboard-Snapshot | docs/qa-ci/status/ | Nein | | Pilot oder Dossier | Datierte Untersuchung, PoC oder einmaliges Audit | docs/qa-ci/archive/ oder docs/dev/ | Nein (außer benannt) | | Implementierungsnotiz | Entwicklerseitiges Schema-, Tool- oder Migrationsdetail | docs/dev/ (tmp/ für Experimente) | Teilweise | {cols="20%,34%,28%,18%"}

1.2. Zweisprachige Single-Source-Kompendien (docs/compendia.json)

Dauerhafte Referenzhandbücher werden als zweisprachige (de/en) Single-Source-Kompendien gepflegt und durch scripts/doc_compendium/ sowie build_compendia.py in MkDocs-Webseiten und gesetzte LuaLaTeX-PDFs übersetzt. Sprachen werden niemals innerhalb einer Datei gemischt und generierte Webseiten nie manuell editiert; gepflegt werden ausschließlich source/chapters/*.{de,en}.md mit 1:1-AST-Blockparität, identischen {#sec:...}- / anchors="..."-Markern, @ref{sec:...}, kanonischen repo:...-Links und reinen ASCII-Codeblöcken (<= 72 Zeichen/Zeile). Vertragsgepinnte Deploy-/Freeze-Dokumente, datierte Workboards und generierte Statusreports bleiben eigenständige Markdown-Dateien.

| Kompendium-ID | Kanonisches source/ | Tracking-Politik | Generierte 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 ]-Schalter, Generierungshinweise, Vorlagen und Checks

  • Navigation & [ DE | EN ]-Sprachumschalter: mkdocs.yml (site_url: https://enpasos.github.io/skillpilot/) paart Compendium (EN)- / Kompendium (DE)-Gruppen und registriert Einzelpaare unter standaloneBilingualPairs in docs/compendia.json. language-switcher.js + bilingual-map.js schalten aktive Sprachseiten um, während einsprachige Betriebs- und Arbeitsdokumente in beiden Modi sichtbar bleiben. Datierte Dossiers und docs/qa-ci/status/-Berichte bleiben über die Abschnitts-index.md erreichbar.
  • Generierungshinweise & Vorlagen: Generierte Markdown-Dateien führen Generated by-, Regenerate with- und Source of truth-Köpfe gemäß generatedMarkdownNoticeRegistry.ts (npm run check:generated-doc-notices, npm run check:generated-status-registry). Dauerhafte QA-Lane-Dokumente folgen Purpose / Source Of Truth / Generated Artifacts / Run / Blocking Semantics / Review Ledger / Review Workflow / Expansion Criteria / Related Documents, Runbooks folgen Run The Audit / Inspect Results / Decide Or Fix An Item / Interpret Diagnostics / Verify Local Changes, und PoC-/Archivdateien tragen ISO-Daten im Dateinamen.
  • Terminologie, Links außerhalb von docs/ und CI-Gates: Das Kernvokabular folgt dem Glossar und checkTerminology.ts (npm run check:terminology). Verweise aus docs/ auf andere Repositorypfade nutzen GitHub-URLs (https://github.com/enpasos/skillpilot/blob/main/... bzw. /tree/main/...), geprüft in .github/workflows/docs_checks.yml:
git diff --check
cd app
npm run check:terminology
npm run check:docs-links
npm run check:docs-indexes