diff --git a/docs/documentation-governance.md b/docs/documentation-governance.md index 797a81b..b8e1803 100644 --- a/docs/documentation-governance.md +++ b/docs/documentation-governance.md @@ -55,12 +55,80 @@ or are generated deterministically.* ## Durchführung / Procedure 1. Geänderte Pfade und benannte Flows erfassen. -2. Zielgruppen und Dokumentfamilien bestimmen. -3. Genau eine der vier Entscheidungen wählen. -4. Pflichtfelder und Evidence ergänzen. -5. Quellen statt generierter Ableitungen ändern. -6. Passende Link-, Renderer-, A11Y-, Plattform- und Fachprüfungen ausführen. -7. Entscheidung im Pull Request erneut prüfen. +2. Zielgruppen bestimmen: Lernende, tägliche Nutzende, + Maintainer/KI-Agenten oder Prüfung/Fehleranalyse. Zusätzlich mindestens einen + betroffenen Leserpfad benennen, zum Beispiel Einstieg, Voraussetzungen, + Vertiefung und nächste sichere Aktion. +3. Kanonische Quelle, Owner, Dokumentklasse und Navigationseinfluss bestimmen. +4. Genau eine der vier Entscheidungen wählen. +5. Sprachstrategie, Sprachpartner, Plattform- und Beispielnachweis ergänzen. +6. Repository-spezifische Distributionsklasse und Sync-Bedarf festhalten. Die + Home Baseline verwendet beispielsweise `homeRuntime`, `sourceOnly` und + `machineLocal`; andere Repositories behalten ihren eigenen Vertrag. +7. Quellen statt generierter Ableitungen ändern. +8. Link-, Renderer-, A11Y-, Plattform- und Fachprüfungen ausführen. +9. Evidence und Re-Evaluation-Trigger festhalten und im Pull Request prüfen. + +*Record the affected audience and at least one concrete reader path, canonical +source and owner, navigation impact, document class, language strategy and +partner, platform and example proof, repository-specific distribution and sync +need, evidence, and reevaluation trigger. Keep semantic review separate from +deterministic validation.* + +## Leserpfade und Progressive Disclosure / Reader Paths and Progressive Disclosure + +**Progressive Disclosure** bedeutet: Der erste Einstieg zeigt Zweck, +Voraussetzungen, Sicherheitsgrenzen und genau eine sichere nächste Aktion. +Vertiefende Erklärungen folgen über beschreibende Links. Ein Leserpfad muss +Voraussetzungen, Reihenfolge, tiefe Referenzen und nächste Aktion nennen. + +Große Dokumente werden nach Aufgabe und Zielgruppe getrennt, wenn eine +gemeinsame Datei Orientierung oder Sprachpflege erschwert. In diesem Fall +bleibt Deutsch der primäre Einstieg und eine nach Repository-Regel benannte +englische Partnerdatei, zum Beispiel `README.EN.md`, bietet einen inhaltlich +gleichwertigen Pfad. Beide Dateien verlinken gegenseitig. +Kurze Dokumente dürfen Deutsch zuerst und Englisch danach enthalten. +Repository-eigene Homogeneity-Prüfungen müssen deklarierte Partnerdateien als +Paar erkennen. Können sie das noch nicht, entsteht ein Tooling-Follow-up statt +einer künstlichen Sprachduplizierung innerhalb jeder Partnerdatei. + +*Progressive disclosure keeps purpose, prerequisites, safety boundaries, and +one safe next action at the first entry. Detailed explanation follows through +descriptive links. Split large documents by task and audience when one file +harms orientation or language maintenance; paired language files remain +semantically equivalent and link to each other. Repository homogeneity checks +must recognize declared language pairs; otherwise record a tooling follow-up +instead of duplicating both languages inside every partner file.* + +## Source und Distribution / Source and Distribution + +Jedes Repository benennt seine eigene kanonische Quelle und den zugehörigen +Default-Branch. Eine getrennte Runtime-, Installations- oder Deployment-Kopie +gilt nur, wenn der Repository-eigene Vertrag sie ausdrücklich definiert. +Dokumentation darf weder Level-0-Pfade noch Distributionsklassen allein wegen +ähnlicher Dateinamen auf andere Repositories übertragen. + +Für die Home Baseline gelten zusätzlich diese lokalen Klassen: + +- `homeRuntime`: kanonisch in Level-0 ändern und nach Lieferung + manifestgesteuert nach `~/` synchronisieren; +- `sourceOnly`: direkt aus der Level-0-Quelle lesen; kein Home-Sync; +- `machineLocal`: nur lokal halten; keine implizite Remote-Autorität. + +Konkrete Home-Runtime-Mitglieder werden ausschließlich im Level-0-Repository +Home Baseline aus `scripts/config/home-sync-manifest.json` abgeleitet. Dieser +Pfad ist in anderen Repositories keine lokale Datei. Andere Repositories +behalten ihre eigenen Begriffe sowie Build-, Installations-, Deployment- oder +Lernreihenverträge. Eine Dokumentationsänderung erweitert keine technische +Propagations- oder Runtime-Zielmenge. + +*Each repository names its own canonical source and default branch. A separate +runtime, installation, or deployment copy exists only when the repository's +own contract defines it. The Home Baseline additionally uses `homeRuntime`, +`sourceOnly`, and `machineLocal`; these terms and its paths are not universal. +Its `scripts/config/home-sync-manifest.json` path belongs to the Level-0 Home +Baseline repository and is not a local path in other repositories. +Documentation changes do not expand technical propagation or runtime targets.* Deterministische Validatoren prüfen Struktur, Pfade, Hashes und Pflichtfelder. Sie können nicht beweisen, dass ein Satz fachlich wahr ist. Dafür bleiben diff --git a/docs/documentation-impact/feature-023-documentation-architecture-adoption.json b/docs/documentation-impact/feature-023-documentation-architecture-adoption.json new file mode 100644 index 0000000..5bf99f9 --- /dev/null +++ b/docs/documentation-impact/feature-023-documentation-architecture-adoption.json @@ -0,0 +1,40 @@ +{ + "schemaVersion": "1.0", + "feature": "023-registered-doc-architecture-adoption", + "entries": [ + { + "changeId": "CHG023", + "scope": "docs/documentation-governance.md", + "decision": "UpdateRequired", + "rationale": "Adopt the portable reader-path, complete Documentation Impact, and repository-specific source/runtime decision contract without changing product or runtime behavior.", + "documents": [ + "docs/documentation-governance.md" + ], + "owner": "Repository Maintainer", + "audiences": [ + "Learners", + "Repository users", + "Maintainers and AI agents", + "Reviewers" + ], + "readerPaths": [ + "Repository entry", + "Documentation governance", + "Maintainer and agent handoff", + "Audit and troubleshooting" + ], + "canonicalSource": "docs/documentation-governance.md", + "navigationImpact": "No new portal; the existing governance reference gains portable decision fields.", + "documentClass": "ActiveSemantic", + "languageStrategy": "German first and English second in one synchronized file.", + "languagePartners": [], + "platformAndExampleProof": "Text-first and platform-neutral; product examples remain unchanged.", + "distributionClass": "sourceOnly", + "homeSyncRequired": false, + "evidence": "docs/documentation-impact/feature-023-documentation-architecture-adoption.json", + "risk": "Low; repository-specific build, runtime, deployment and learning contracts remain authoritative.", + "criticality": "Normal", + "reevaluationTrigger": "The documentation architecture, reader paths, or repository source/runtime contract changes." + } + ] +} diff --git a/docs/project-statistics.md b/docs/project-statistics.md index eb7104d..0162414 100644 --- a/docs/project-statistics.md +++ b/docs/project-statistics.md @@ -446,25 +446,25 @@ Profil 2 verwendet Git-getrackte Textdateien und sichtbare Git-Aktivitaet. Die W | Kennzahl / Metric | Wert / Value | |---|---:| -| Textbasis / Text base | 138642 lines | -| Textdateien / Text files | 965 | -| Beobachtbarer Zeitraum / Observable period | 2025-08-03..2026-07-31 | +| Textbasis / Text base | 138750 lines | +| Textdateien / Text files | 966 | +| Beobachtbarer Zeitraum / Observable period | 2025-08-10..2026-08-02 | | Aktivtage / Active days | 128 | -| Relevante Commits / Relevant commits | 673 | -| Zeilen je Aktivtag / Lines per active day | 1083.1 | +| Relevante Commits / Relevant commits | 651 | +| Zeilen je Aktivtag / Lines per active day | 1084.0 | | Peak-Tag im Fenster / Peak day in window | 2026-04-19 / 107974 | | Peak-Woche im Fenster / Peak week in window | 2026-04-19 / 114277 | | Laengste Serie / Longest streak | 11 days | | Speedup vs. 80 lines/day | 13.5x | | Speedup vs. 100 lines/day | 10.8x | -| Methodik / Methodology | v2; source `23b3418f3ade` | +| Methodik / Methodology | v2; source `fc865a7d1135` | ### Artefaktmix / Artifact Mix ```text Produktiv / Production [#...................] 7.4% | 10220 Tests [#...................] 4.1% | 5745 -Dokumentation / Documentation [##############......] 71.8% | 99582 +Dokumentation / Documentation [##############......] 71.8% | 99690 Skripte / Scripts [###.................] 13.0% | 18014 Konfiguration / Configuration [#...................] 1.9% | 2678 Daten und Medien / Data and media [#...................] 0.8% | 1150 @@ -478,25 +478,25 @@ Die Balken teilen die aktuelle getrackte Textbasis in stabile Kategorien. Prozen ### Tagesaktivitaet / Daily Activity ```text -Wochen / Weeks 01..26 | 2025-08-03..2026-01-31 -So/Su 4 2 2 1 2 2 0 0 0 1 0 0 3 4 1 4 2 0 2 3 0 0 0 0 0 0 -Mo/Mo 1 0 0 0 1 1 0 0 0 0 1 0 1 3 2 2 3 3 1 0 0 0 0 0 0 0 -Di/Tu 0 0 1 0 1 1 0 0 0 0 3 0 1 4 0 0 1 1 0 2 0 0 0 0 0 0 -Mi/We 0 0 0 0 1 0 0 0 0 0 0 0 2 0 3 0 4 1 0 0 0 0 0 2 2 0 -Do/Th 0 0 0 0 0 0 0 0 0 0 0 1 2 1 3 0 4 3 0 0 0 0 0 1 1 0 -Fr/Fr 0 0 1 0 0 0 0 1 0 0 0 0 1 0 3 2 3 0 0 0 0 0 0 1 2 0 -Sa/Sa 0 3 1 2 2 0 0 0 0 0 0 2 2 3 2 4 0 0 0 0 0 0 0 0 1 2 +Wochen / Weeks 01..26 | 2025-08-10..2026-02-07 +So/Su 2 2 1 2 2 0 0 0 1 0 0 3 4 1 4 2 0 2 3 0 0 0 0 0 0 0 +Mo/Mo 0 0 0 1 1 0 0 0 0 1 0 1 3 2 2 3 3 1 0 0 0 0 0 0 0 3 +Di/Tu 0 1 0 1 1 0 0 0 0 3 0 1 4 0 0 1 1 0 2 0 0 0 0 0 0 0 +Mi/We 0 0 0 1 0 0 0 0 0 0 0 2 0 3 0 4 1 0 0 0 0 0 2 2 0 0 +Do/Th 0 0 0 0 0 0 0 0 0 0 1 2 1 3 0 4 3 0 0 0 0 0 1 1 0 0 +Fr/Fr 0 1 0 0 0 0 1 0 0 0 0 1 0 3 2 3 0 0 0 0 0 0 1 2 0 2 +Sa/Sa 3 1 2 2 0 0 0 0 0 0 2 2 3 2 4 0 0 0 0 0 0 0 0 1 2 0 ``` ```text -Wochen / Weeks 27..52 | 2026-02-01..2026-08-01 -So/Su 0 0 0 0 0 4 0 4 0 0 2 4 0 0 0 0 0 1 0 4 0 0 0 1 4 3 -Mo/Mo 3 0 0 0 0 0 0 0 2 0 1 4 0 4 0 0 0 0 0 0 0 3 1 4 4 0 -Di/Tu 0 0 0 0 0 2 0 0 3 0 0 0 0 3 0 0 3 0 0 0 0 2 0 3 4 4 -Mi/We 0 0 0 0 0 0 0 1 0 0 0 3 0 2 0 0 0 2 0 4 0 2 0 0 2 4 -Do/Th 0 0 0 0 0 0 0 0 0 0 0 0 4 0 0 0 1 0 4 1 0 0 0 1 4 0 -Fr/Fr 2 0 0 0 0 0 0 2 4 0 2 4 0 0 0 4 2 2 0 3 2 3 4 4 4 1 -Sa/Sa 0 0 0 0 0 0 0 2 0 0 0 0 0 0 0 0 0 0 0 4 0 4 4 0 4 - +Wochen / Weeks 27..52 | 2026-02-08..2026-08-08 +So/Su 0 0 0 0 4 0 4 0 0 2 4 0 0 0 0 0 1 0 4 0 0 0 1 4 3 1 +Mo/Mo 0 0 0 0 0 0 0 2 0 1 4 0 4 0 0 0 0 0 0 0 3 1 4 4 0 - +Di/Tu 0 0 0 0 2 0 0 3 0 0 0 0 3 0 0 3 0 0 0 0 2 0 3 4 4 - +Mi/We 0 0 0 0 0 0 1 0 0 0 3 0 2 0 0 0 2 0 4 0 2 0 0 2 4 - +Do/Th 0 0 0 0 0 0 0 0 0 0 0 4 0 0 0 1 0 4 1 0 0 0 1 4 0 - +Fr/Fr 0 0 0 0 0 0 2 4 0 2 4 0 0 0 4 2 2 0 3 2 3 4 4 4 1 - +Sa/Sa 0 0 0 0 0 0 2 0 0 0 0 0 0 0 0 0 0 0 4 0 4 4 0 4 2 - ``` DE: 0 = keine Aenderung; 1 = 1..79; 2 = 80..399; 3 = 400..1599; 4 = 1600+ geaenderte Textzeilen; - = noch nicht abgelaufen. @@ -506,24 +506,24 @@ DE: 0 = keine Aenderung; 1 = 1..79; 2 = 80..399; 3 = 400..1599; 4 = 1600+ geaend ### Wochenvolumen / Weekly Volume ```text -Wochen / Weeks 01..26 | 2025-08-03..2026-01-31 +Wochen / Weeks 01..26 | 2025-08-10..2026-02-07 cap 100000 | . . . . . . . . . . . . . . . . . . . . . . . . . . - 83333 | . . . . . . . . . . . . . # . . . . . . . . . . . . - 66667 | . . . . . . . . . . . . . # . . . . . . . . . . . . - 50000 | . . . . . . . . . . . . . # . . . . . . . . . . . . - 33333 | . . . . . . . . . . . . . # . . . . . . . . . . . . - 16667 | . . . . . . . . . . . . . # . . . . . . . . . . . . + 83333 | . . . . . . . . . . . . # . . . . . . . . . . . . . + 66667 | . . . . . . . . . . . . # . . . . . . . . . . . . . + 50000 | . . . . . . . . . . . . # . . . . . . . . . . . . . + 33333 | . . . . . . . . . . . . # . . . . . . . . . . . . . + 16667 | . . . . . . . . . . . . # . . . . . . . . . . . . . 0 +----------------------------------------------------- ``` ```text -Wochen / Weeks 27..52 | 2026-02-01..2026-08-01 +Wochen / Weeks 27..52 | 2026-02-08..2026-08-08 cap 200000 | . . . . . . . . . . . . . . . . . . . . . . . . . . 166667 | . . . . . . . . . . . . . . . . . . . . . . . . . . 133333 | . . . . . . . . . . . . . . . . . . . . . . . . . . - 100000 | . . . . . . . . . . . # . . . . . . . . . . . . . . - 66667 | . . . . . . . . . . . # . . . . . . . . . . . . . . - 33333 | . . . . . . . . . . . # . . . . . . . . . . . . # . + 100000 | . . . . . . . . . . # . . . . . . . . . . . . . . . + 66667 | . . . . . . . . . . # . . . . . . . . . . . . . . . + 33333 | . . . . . . . . . . # . . . . . . . . . . . . # . . 0 +----------------------------------------------------- ``` @@ -534,23 +534,23 @@ Das Wochenvolumen zeigt Additionen plus Loeschungen. Es ist Aenderungsaktivitaet ### Kumulative Entwicklung / Cumulative Development ```text -Wochen / Weeks 01..26 | 2025-08-03..2026-01-31 +Wochen / Weeks 01..26 | 2025-08-10..2026-02-07 cap 200000 | . . . . . . . . . . . . . . . . . . . . . . . . . . 166667 | . . . . . . . . . . . . . . . . . . . . . . . . . . 133333 | . . . . . . . . . . . . . . . . . . . . . . . . . . - 100000 | . . . . . . . . . . . . . . . . # # # # # # # # # # - 66667 | . . . . . . . . . . . . . # # # # # # # # # # # # # - 33333 | . . . . . . . . . . . . . # # # # # # # # # # # # # + 100000 | . . . . . . . . . . . . . . . # # # # # # # # # # # + 66667 | . . . . . . . . . . . . # # # # # # # # # # # # # # + 33333 | . . . . . . . . . . . . # # # # # # # # # # # # # # 0 +----------------------------------------------------- ``` ```text -Wochen / Weeks 27..52 | 2026-02-01..2026-08-01 +Wochen / Weeks 27..52 | 2026-02-08..2026-08-08 cap 500000 | . . . . . . . . . . . . . . . . . . . . . . . . . . 416667 | . . . . . . . . . . . . . . . . . . . . . . . . . . - 333333 | . . . . . . . . . . . . . . . . . . . . . . . . # # - 250000 | . . . . . . . . . . . . # # # # # # # # # # # # # # - 166667 | . . . . . . . . . . . # # # # # # # # # # # # # # # + 333333 | . . . . . . . . . . . . . . . . . . . . . . . # # # + 250000 | . . . . . . . . . . . # # # # # # # # # # # # # # # + 166667 | . . . . . . . . . . # # # # # # # # # # # # # # # # 83333 | # # # # # # # # # # # # # # # # # # # # # # # # # # 0 +----------------------------------------------------- ``` @@ -604,7 +604,7 @@ Die Faktoren vergleichen sichtbare Lieferdichte mit den dokumentierten manuellen Scale: 0..2000 lines/day Experienced manual [#...................] 80 Thorsten solo [#...................] 100 -Visible repository [###########.........] 1083.1 +Visible repository [###########.........] 1084.0 ``` Die gemeinsame Skala vergleicht Referenzen und sichtbare Lieferdichte. Sie schreibt die Git-Aktivitaet keiner Person oder KI pauschal zu. @@ -613,13 +613,12 @@ Die gemeinsame Skala vergleicht Referenzen und sichtbare Lieferdichte. Sie schre ### Textalternative / Text Alternative -DE: Das Fenster beginnt am 2025-08-03 und endet am 2026-07-31. Es enthaelt 128 aktive und 235 inaktive vergangene Tage. Peak-Tag: 2026-04-19 / 107974. Peak-Woche: 2026-04-19 / 114277. Laengste Serie: 11 Tage (2025-10-25..2025-11-04). +DE: Das Fenster beginnt am 2025-08-10 und endet am 2026-08-02. Es enthaelt 128 aktive und 230 inaktive vergangene Tage. Peak-Tag: 2026-04-19 / 107974. Peak-Woche: 2026-04-19 / 114277. Laengste Serie: 11 Tage (2025-10-25..2025-11-04). -*EN: The window starts on 2025-08-03 and ends on 2026-07-31. It contains 128 active and 235 inactive elapsed days. Peak day: 2026-04-19 / 107974. Peak week: 2026-04-19 / 114277. Longest streak: 11 days (2025-10-25..2025-11-04).* +*EN: The window starts on 2025-08-10 and ends on 2026-08-02. It contains 128 active and 230 inactive elapsed days. Peak day: 2026-04-19 / 107974. Peak week: 2026-04-19 / 114277. Longest streak: 11 days (2025-10-25..2025-11-04).* | Monat / Month | Geaenderte Textzeilen / Changed text lines | |---|---:| -| 2025-08 | 3503 | | 2025-09 | 633 | | 2025-10 | 1992 | | 2025-11 | 102936 | @@ -631,5 +630,6 @@ DE: Das Fenster beginnt am 2025-08-03 und endet am 2026-07-31. Es enthaelt 128 a | 2026-05 | 13510 | | 2026-06 | 37685 | | 2026-07 | 72048 | +| 2026-08 | 158 |