Doku-UX-Konzept — Struktur · Lesbarkeit · Navigation entwirren
Status: lebend (Konzept ✅, Umsetzung phasenweise) · Bezug: OP-DOCS-13 (Owning-Doc) · OP-DOCS-4/-9/-10/-11 · Zielgruppe: IT-Dev/Architektur · Business/Management (Governance) · Customer Service (mittelbar) · True North: bedient die „schneller"-Klausel (die Leitplanke erlaubt direkter · schneller · genauer) — bessere Struktur/Navigation macht die Antworten auf alle drei Leitfragen schneller auffindbar (beantwortet sie nicht inhaltlich selbst; das tun die Produkt-/Fach-Docs).
Kernaussage. Die Taktano-Doku ist inhaltlich vollständig und technisch gut gerendert (Docusaurus · Offline-Suche · Glossar-Sprechblasen · Mermaid), wirkt aber „verworren" — das ist ein Struktur-, Redundanz- und Dichte-Problem, kein Inhaltsproblem. Wir lösen es nicht-invasiv (keine Datei-Verschiebungen, keine Umbenennungen) in fünf einzeln lieferbaren Phasen: erst Drift-Bugs fixen, dann Leitplanken einmal besitzen statt mehrfach wiederholen, dann Navigation (generierte Landkarte + „Zur Landkarte"-Footer), dann Lesbarkeit (pyramidale Kernaussage-Blöcke, Mega-Zeilen brechen), zuletzt das OP-Register aus einer Quelle generieren. Muster-Vorlage für jeden Anti-Drift-Fix ist der bestehende Glossar-Generator (
docs-site/src/glossar/glossar.mjs→gen-glossar.mjs): eine Datenquelle → generierte, nie handeditierte.md, Build bricht bei Fehlern hart.
1. Warum es „verworren" wirkt — fünf Ursachen (die Diagnose)
Belegbasiert eingegrenzt (drei Explore-Analysen). Es sind fünf sich verstärkende Faktoren:
| # | Ursache | Beleg (Beispiel) |
|---|---|---|
| 1 | Mensch- und Maschinen-Doku im selben Prosastrom. Agenten-/Prozess-Docs (CLAUDE.md, konventionen/agents.md, HANDOFF.md, CHANGELOG.md, die OP-Maschinerie) sind für KI-Agenten/Commit-Nachvollzug geschrieben — und sind das Erste, was ein menschlicher Leser trifft (Pflicht-Reihenfolge HANDOFF → Lastenheft → agents.md, alle drei schwer). | Read-Order in agents.md §4 |
| 2 | Riesiger OP-ID-Namensraum als Kurzschrift-Prosa. ~155 OP-IDs in ~59 Familien; Sätze parsen nur mit Code-Kenntnis. | 1.866 rohe OP--Referenzen allein in HANDOFF.md |
| 3 | Leitplanken mehrfach wörtlich statt einmal besessen. Dieselbe Regel steht in vielen Dateien. | True North (~15 Dateien) · OP-DOCS-9 (3×) · OP-PM-2 (2×) · ID-Legende (4×) |
| 4 | Vier überlappende OP-/Entscheidungs-Indizes. Jeder verteidigt „kein Duplikat" per Prosa — selbst ein Symptom. | HANDOFF §4 · IDs.md · Register.md · Roadmap.md → bereits als OP-DOCS-11 erfasst |
| 5 | Extreme physische Dichte. Einzelzeilen von 5.000–15.284 Zeichen in HANDOFF §4; je ein Riesen-Absatz pro PR in CHANGELOG.md → kein Scannen, kein sinnvolles Diff, verletzt das eigene Pyramiden-Gebot. | HANDOFF §4 OP-Einträge |
Navigation zusätzlich: drei parallel handgepflegte Nav-Repräsentationen (README-Landkarte ·
_category_.json · Frontmatter) driften auseinander; zwei getrennte Docusaurus-Sidebars (/docs vs.
/projekt) ohne Querverweis; 20 von 41 Leaf-Docs sind Navigations-Sackgassen (alle 16 architektur/)
ohne Rücklink; zwei überlappende „Lesepfade"-Systeme; architektur/ ist ein flacher Eimer aus 16 Ein-OP-Dateien.
2. Zielbild — drei Ebenen, auf das bestehende Layout abgebildet (nicht-invasiv)
Kein Umzug: Wir markieren und verlinken, statt zu verschieben — das schützt alle bestehenden Links und die Git-Historie (Leitprinzip Einfachheit).
| Ebene | Inhalt | Fix |
|---|---|---|
| (i) Mensch/Fach/Produkt | fachlich/ · produkt/ · glossar/ · zielgruppen/ · architektur/ + menschliche betrieb/-Docs | Die Vorderseite — ein Zielgruppen-Einstieg führt hierher |
| (ii) Way-of-Working / Agenten | konventionen/ · CLAUDE.md · betrieb/Tests.md · betrieb/Timesheet.md | Sichtbares „Prozess-/Maschinen-Doku"-Signal → Mensch routet sich selbst weg |
| (iii) Append-only Audit-Logs | HANDOFF.md · CHANGELOG.md | Schon per /projekt-Instanz getrennt — nur brücken + entdichten |
3. Roadmap — fünf Phasen, quick-wins first
Jede Phase ist eigenständig lieferbar. Der Glossar-Generator ist das wiederverwendete Muster für alle generierten Views (Landkarte, OP-Register) — eine Quelle, hart validiert, nie handeditiert.
| Phase | Ziel | Kern-Änderung | Advanciert OP |
|---|---|---|---|
| 1 · Drift-Fixes ✅ (dieser PR) | Jeden konkreten Bug beheben, Zielgruppen-Arbeit entsperren | Zielgruppen 4→7 in glossar.mjs; Positions-Clash; stale _category_.json/Pfade; Topic-Split-Querlinks | OP-DOCS-9/-10 |
| 2 · Leitplanken-Single-Source ✅ (dieser PR) | Jede Regel einmal besitzen, sonst verlinken | CLAUDE.md-Blöcke OP-DOCS-9 + OP-PM-2 auf Essenz + Owner-Pointer (agents.md §5.1/§6.5/§6.6) gekürzt; True-North-Owner-Link in Lesepfade.md. (SemVer & ID-Legende sind bereits single-source: version.ts→CLAUDE.md, IDs.md.) | OP-DOCS-9 |
| 3 · Navigation ✅ (inkl. 3b) | Ein Einstieg, keine Sackgassen, gebrückte Sidebars | ✅ Lesepfade.md als Vordertür (Aufgaben-Tabelle aus README gefaltet) · ✅ „Zur Landkarte"-Remark-Footer (src/remark/docNavFooter.mjs, Site) — seit 07-12 zusätzlich statisch im Markdown (scripts/gen-doc-footer.mjs, idempotent; das Doku-Review D5 hatte belegt, dass die Sackgassen auf GitHub offen blieben) · ✅ Sidebar-Brücke /docs↔/projekt · ✅ konventionen als Prozess-/Agenten-Tier gelabelt. Phase 3b ✅: (a) architektur/-Bänder (16 Docs → 5 thematische Sidebar-Bänder); (b) Landkarte-Konsistenz per gehärtetem Gate statt Generierung — die README-Vollständigkeit war in check-doc-consistency.sh §4 bereits geprüft, daher (Nutzer-Entscheidung, Einfachheit) den Gate erweitert (3-Ebenen-Glob · sidebar_position-Eindeutigkeit je Ordner · Zielgruppen-Parität glossar.mjs↔Lesepfade) statt die kuratierten Tabellen zu generieren. | OP-DOCS-4 · OP-DOCS-13 |
| 4 · Lesbarkeit 🟡 (weitgehend) | Pyramidal überall, keine Mega-Zeilen | ✅ Kernaussage-Blöcke in 7 schweren Docs (Lastenheft · HANDOFF · 5× architektur/) · ✅ HANDOFF §4 entdichtet (19 byte-identische Dubletten raus, 226→207) · ✅ §4-Format-Konvention (agents.md §6.2) · ✅ 07-12 (Doku-Review E6): kanonischer Kopf-Standard (Status/Bezug/Zielgruppe/True-North + genau eine Kernaussage) in allen 16 architektur/-Docs, als Regel in agents.md §2.1 + Warn-Gate (check-doc-consistency.sh §10); Zeilenlängen-Warnung > 2000 Z. aktiv. Offen: near-identische Mega-Zeilen im §4-Archiv (z. B. OP-OPT-1 ×2) per gezielter Glätt-Runde; CHANGELOG bleibt append-only/terse. Status/Rest: ops/OP-DOCS-13.md. | OP-DOCS-13 |
| 5 · OP-Single-Source ✅ (anders gelöst) | Ein OP-Datenfile als Quelle | Umgesetzt über den OP-Management-Gold-Standard (OP-DOCS-11): ops/<ID>.md (Frontmatter, hart validiert) → generierte Offene-Punkte.md (inkl. Migrations-Zähler) + GitHub-Issues-Spiegel; seit 07-12 verbindlich (agents.md §6.2 ops/-first, HANDOFF §4 = Archiv). Die hier ursprünglich skizzierte Variante (src/op/op.mjs generiert Register/IDs/HANDOFF §4/Roadmap) ist verworfen — Register/IDs bleiben kuratierte Indizes, §4 wird nicht regeneriert, sondern stirbt als Archiv aus. | OP-DOCS-11 |
Governance gegen Re-Drift (Stand 07-12, OP-DOCS-14 Teil 3 ✅): scripts/check-doc-consistency.sh
prüft zweistufig — die harte Teilmenge blockt den Merge (--strict im CI-Job doc-consistency
am ci-gate: tote Links · Version-Single-Source; plus blockierender Staleness-Diff der generierten
Offene-Punkte.md), der Rest warnt (Zielgruppen-Parität, sidebar_position-Eindeutigkeit,
Log-Zeilenlängen > 2000 Zeichen, Footer-Staleness README/HANDOFF, Landkarte-Rücklink).
Der Docusaurus-Build ist seit 07-12 tatsächlich das Broken-Link-Gate (onBrokenLinks: 'throw' —
zuvor stand er entgegen dieser Zeile auf warn, Doku-Review D5). Offen: OP-ID-Existenz-Check.
4. Messbare Zielkriterien (Definition of Done je Dimension)
- Struktur: jede
docs/-Datei ist genau einer der drei Ebenen zugeordnet; keine stale_category_.json-Aufzählung. - Lesbarkeit: keine Zeile in
HANDOFF.md/CHANGELOG.md> N Zeichen (Governance-Gate); jedes schwere Doc hat einen> **Kernaussage.**-Block. - Navigation: 0 Leaf-Docs ohne „Zur Landkarte"-Rücklink; ein einziger kanonischer Rollen-Einstieg; Sidebars gegenseitig verlinkt.
- UX/Konsistenz: Zielgruppen-Taxonomie in
glossar.mjs==Lesepfade.md(heute 4 vs. 7 → Phase 1 behebt); jede wiederholte Leitplanke hat genau einen Owner.
5. OP-DOCS-13 (Definition)
OP-DOCS-13 — Roh-Lesbarkeit & Navigationslast der Doku senken. Problem: Mega-Zeilen (5k–15k Z.) in
HANDOFF §4/CHANGELOG; ID-Kurzschrift-Prosa; 20/41 Leaf-Docs sind Sackgassen (alle 16architektur/); schweren Docs fehlt der pyramidale Kernaussage-Block. Ziel: pyramidale TL;DR-Blöcke, zeilen-/bullet-strukturierte Logs, generierte Rück-/Quer-Navigation (Remark-Plugin), OP-ID-Hover-Gloss. Messbar: keine Log-Zeile > N Zeichen; jedes Leaf-Doc hat Kernaussage + „Zur Landkarte". Abgrenzung: die OP-Verwaltungs-Redundanz ist OP-DOCS-11; die Anwender-/Intern-Trennung ist OP-DOCS-4/-5 — OP-DOCS-13 ist die Roh-Lesbarkeit/Navigationslast.
↩ Zurück zur Doku-Landkarte · verwandt: Lesepfade · Register (alle OPs) · agents.md