doc-refine – Leitfaden zur Optimierung der Lesbarkeit technischer Dokumentation
Abgrenzung von Review und Überarbeitung
Zunächst ist zwischen Review und Überarbeitung zu unterscheiden: Wird nur eine Prüfung gewünscht, werden Probleme und Vorschläge geliefert. Wird explizit eine Änderung gefordert, wird nur die autorisierte Dokumentation geändert. Betrifft eine Änderung Verhalten oder Fakten und nicht nur den Ausdruck, bleibt der Originaltext erhalten, und es wird auf den zu bestätigenden Teil hingewiesen.
Schutz vor Verdichtung: Technisches Verhalten, API-/Datenverträge, Voraussetzungen und Randbedingungen, Sicherheits- und Rechtswarnungen, Alternativbeschreibungen zur Barrierefreiheit, gültige Beispiele, Quelllinks und stabile Ankerpunkte. Dass das Verhalten bereits im Code vorhanden ist, reicht nicht als Grund für die Löschung in der Dokumentation; lokal notwendige Wiederholungen können das eigenständige Lesen unterstützen.
Zwei Prüfziele
Alle Entscheidungen lassen sich auf zwei Fragen zurückführen:
| Axiom | Frage an sich selbst | Kurzform |
|---|---|---|
| ① Schnell auffindbar | Erkennt die Zielgruppe aus dem Inhaltsverzeichnis und den Überschriften, wo die Informationen stehen? | Wegweiser klar |
| ② Jeder Abschnitt hat einen Zweck | Geht beim Löschen Information verloren, die zum Erledigen einer Aufgabe, zum Verstehen des Verhaltens oder zur Risikokontrolle benötigt wird? | Information vollständig & prägnant |
Führen Sie beide Prüfungen für jeden Abschnitt durch. Wenn ① nicht erfüllt ist → Überschrift ändern / Diagramm hinzufügen / Struktur anpassen. Wenn ② nicht erfüllt ist → Geschützte Elemente und Leseraufgaben prüfen, dann Zusammenlegung oder Kürzung vorschlagen; nicht aus Umfangsgründen notwendige Inhalte löschen.
Arbeitsablauf
1. Diagnose (erst vollständig lesen, nicht sofort ändern)
Das gesamte Ziel dokument durchlesen, Abschnitt für Abschnitt Probleme notieren:
- Kann die Überschrift ohne Nummerierung den Inhalt eigenständig vermitteln? (Nein → Axiom ① verletzt)
- Tritt dieselbe Logik/Regel an 2+ Stellen auf? (Ja → Axiom ② verletzt)
- Hilft diese Verhaltensbeschreibung dem Leser, den Vertrag, die Einschränkung oder das Ergebnis zu verstehen? Zuerst den Zweck beurteilen, nicht mechanisch nach „Was ist das / Warum“ löschen.
- Enthält die Einleitung nur wiederholende Vorworte? Kann sprachlich gestrafft werden, aber die darin enthaltene Schrittpositionierung, Warnung oder Einschränkung bleibt erhalten.
- Sind 3+ Vergleiche in Fließtext verstreut? (Ja → Tabelle verwenden)
- Ist ein Diagramm besser geeignet, um Abläufe oder Zustände zu verstehen? Nach den Fähigkeiten des Zielrenderers Mermaid wählen oder Text beibehalten.
- Lösen die Beispiele echte Fragen, Fehlerbehebungen oder Randfälle? Beispiele erhalten, die für die Zielgruppe nützlich sind.
2. Reparatur (nach Axiomen kategorisiert anwenden)
Die konkreten Regeln finden Sie in den Abschnitten §Axiom ① und §Axiom ② unten.
3. Validierung (quantitative Basis)
Nach der Reparatur bei Bedarf die Prüfliste lesen, um Informationsvollständigkeit und Leseeffekt zu prüfen. Nicht jeder Wert muss erreicht werden – sie sind Diagnosewerkzeuge, kein Gesetz; bei klarer Priorität kann davon abgewichen werden.
Axiom ①: Schnell auffindbar
Erkennbarkeit von Überschriften
Überschriften sind Wegweiser. Ein Betreuer des Inhaltsverzeichnisses sollte auf einen Blick erkennen, was in jedem Abschnitt steht.
Bewertungskriterium: Wenn Sie in den Abschnitt klicken müssen, um zu wissen, worum es geht, ist die Überschrift zu allgemein.
| ❌ Zu allgemein | ✅ Erkennbar | Warum geändert? |
|---|---|---|
5.1 Tabellenebene | 5.1 CRUD für Projekte (Tabellenebene-Endpunkte) | „Tabellenebene" kann alles Mögliche sein |
5.3 Zeilenebene | 5.3 Kollaborationsendpunkte auf Zeilenebene | Der Leser weiß, dass es hier um Übernahme, Abgabe usw. geht |
5.4 Export | 5.4 Vollständiger CSV-Export | Welches Format? Vollständig oder teilweise? |
Endpunkte | HTTP-Endpunkte | Mehrdeutigkeit beseitigt |
Tipp: Bei zu kurzen Kernkonzepten mit Klammerbegriffen wichtige Informationen ergänzen. Aber nicht übertreiben – Ziel ist ≤15 Zeichen, um zu vermitteln: „Was ist in diesem Abschnitt?", keine wissenschaftliche Arbeit.
Informationsarchitektur
- Ein Abschnitt, eine Aufgabe: Nach der primären Leseraufgabe (Tutorial, Anleitung, Referenz oder Erklärung) organisieren; benötigte API-Signaturen oder kurze Hintergrundinformationen können bleiben, lange Materialien per Cross-Reference verlinken.
- Wichtigstes zuerst, Details später: Die wichtigsten Informationen an den Anfang des Abschnitts oder der Seite stellen (Progressive Disclosure). Fortgeschrittene/Randinformationen können eingeklappt oder im Anhang untergebracht werden.
- Prinzip der Eigenständigkeit: Ein Betreuer sollte von jeder Seite aus lesen können, ohne Vorkenntnisse (Every Page is Page One). Wenn Vorkonzepte erforderlich sind, am Anfang des Abschnitts deklarieren und verlinken.
Diagramme und Alternativtexte
Diagramme nur verwenden, wenn Beziehungen, Abläufe oder Vergleiche dadurch klarer werden; durchsuchbare Texte und notwendige Alternativbeschreibungen erhalten.
Entscheidungsbaum:
Informationstyp?
├─ Mehrschrittiger Ablauf / mit Verzweigungen → Flussdiagramm (flowchart)
├─ Ereignisgesteuerte Zustandsänderungen → Zustandsdiagramm (stateDiagram-v2)
├─ 3+ Elemente × 2+ Dimensionen vergleichen → Tabelle
├─ Komponentenbeziehungen / Architekturebenen → Schema + Schichten
├─ Definitionen / Kontext / genaue Werte → Text (Standard)
└─ Unsicher → Standardtext (Diagramme sind Beiwerk, nicht Dekoration)
Bewährte Praktiken für Mermaid:
- Knoten ≤30 – darüber hinaus wird der Layout-Algorithmus unlesbar, aufteilen in „Übersicht → Details"-Mehrfachdiagramme
- Verzweigungsbedingungen und unklare Beziehungen mit Labels versehen; klare Abfolgepfeile können ohne Label bleiben, um Rauschen zu vermeiden
- Verwandte Knoten mit
subgraphgruppieren TD(Top-Down) geeignet für Hierarchien;LR(Links-Rechts) geeignet für Sequenzen/Fließbänder
Tabellendesign (Tufte-Prinzipien):
- Überflüssige Linien, Hintergründe und reine Dekoration entfernen – „Above all else show the data"
- Minimale sinnvolle Unterschiede: Visuelle Unterscheidungen so subtil wie möglich, aber klar
- Zahlen spaltenweise ausrichten, um Vergleich zu erleichtern
- Text immer horizontal, keine vertikale Anordnung
Axiom ②: Jeder Abschnitt hat einen Zweck
Redundanzen vermeiden
Dasselbe Information an mehreren Stellen ist der größte Feind der Wartbarkeit – eine Änderung an einer Stelle, die andere wird vergessen.
Erkennungskriterien (wenn eines zutrifft → Redundanz vermeiden):
- Dieselbe Logik/Regel tritt in 2+ Abschnitten auf → Hauptquelle behalten (normalerweise Datenmodell oder Zustandsmaschine), restliche durch Cross-Reference ersetzen
- Nach Prüfung von Verhalten, Voraussetzungen, Risiken und eigenständigem Lesen ergibt sich kein Informationsverlust → Zusammenlegen oder kürzen
- Dokumentation wiederholt Implementierungsdetails → Prüfen, ob der Leser sie benötigt; Verhaltensbeschreibung und Vertrag erhalten, nicht mit „Code enthält es bereits" als Grund für Löschung
- Mehrere gleichwertige Ansätze → Standardempfehlung geben; notwendige Alternativen mit unterschiedlichen Kompatibilitäts-, Berechtigungs- oder Verwendungsbedingungen erhalten
ARID ≠ DRY: Dokumentation akzeptiert notwendige Wiederholungen – es ist sinnvoll, Konzepte aus Referenzabschnitten in Tutorials zu wiederholen. Aber parallele Wartung vermeiden: Ein Fakt darf nicht an zwei Stellen unabhängig verwaltet werden, sonst ist eine Stelle garantiert veraltet.
Kürzung
Alles entfernen, was nicht den aktuellen Bedürfnissen des Lesers dient.
| Geruchsmerkmal | Korrektur | Warum |
|---|---|---|
| Wiederholende Vorworte: „In diesem Abschnitt werden wir …" | In direkte Aussage umwandeln | Notwendige Schrittpositionierung erhalten |
| Füllwörter: „Es ist zu beachten" / „Erwähnenswert ist" | Einleitungen kürzen | Warnungen oder Einschränkungen selbst müssen bleiben |
| Häufige Passivkonstruktionen („wird verwendet", „wird … werden") | In aktives SVO umwandeln | Kürzer, klarer, Leser weiß, „wer was tut" |
| Synonymwanderung (dasselbe Feature mit verschiedenen Begriffen) | Terminologie vereinheitlichen, ein Begriff eine Bedeutung | Leser weiß genau, wie das Feature heißt |
| Schwer lesbare lange Schachtelsätze | Logisch aufteilen | Zusammenhang von Bedingungen, Ausnahmen und Ergebnissen nicht auseinanderreißen |
| Aufzählung gleichwertiger Optionen | Empfehlung zuerst, notwendige Alternativen danach | Unterschiedliche, gültige Optionen unter verschiedenen Einschränkungen erhalten |
Zurückhaltung bei Beispielen
Beispiele sind das stärkste Werkzeug für schnelle Antworten, aber auch der am häufigsten missbrauchte Inhaltstyp. Write the Docs schreibt bewusst „Include (some) examples" – die Klammer um „some" ist eine bewusste Einschränkung.
Wann Beispiele sinnvoll sind:
- Der Leser braucht eine schnelle Antwort und springt direkt zu Beispielen (häufigste erste Reaktion)
- Ein Konzept ist ohne konkretes Beispiel schwer zu verstehen
- Hochfrequente, reale Anwendungsfälle demonstrieren
Wann Beispiele nicht sinnvoll sind:
- Wenn Offensichtliches demonstriert wird (Microsoft: „Don't illustrate obvious points")
- Künstliche Szenarien, die das Verständnis nicht fördern; synthetische Beispiele, die klar gekennzeichnet sind und deren Verhalten überprüfbar ist, können bleiben
- Nur aus „Vollständigkeit", ohne tatsächliches Benutzerbedürfnis
- Es gibt bereits genug Beispiele – weitere senken die Scanbarkeit
Gute Beispiele:
- Nur die häufigsten Anwendungsfälle abdecken, keine Vollständigkeit anstreben
- In sich geschlossen und ausführbar (Kopieren und Einfügen funktioniert)
- Von einfach zu komplex aufsteigend
- Erwartete Ausgabe zeigen, damit der Leser überprüfen kann
- Boilerplate nur weglassen, wenn das Beispiel weiterhin ausführbar ist oder die Voraussetzungen klar sind; notwendige imports, Fehlerbehandlung und erwartete Ausgabe erhalten
Schlechte Beispiele:
- Demonstrieren Offensichtliches
- Nicht realistische, konstruierte Szenarien
- Ein Beispiel versucht, zu viele Variablen abzudecken
- Fügen für das Beispiel irrelevante Ausnahmebehandlungen ein
- Nicht verifizierter Code, der als ausführbar angegeben wird; bei Nichtausführbarkeit die Validierungseinschränkung klar angeben
Positionsregeln:
- Einfache, einzeilige Beispiele → inline im Text
- Längere Beispiele → getrennt von dichten Referenzmaterialien (eigener Absatz oder aufklappbarer Bereich)
- Beispiele in Referenzdokumentation → zurückhaltend, nur zur Nutzungserklärung, nicht mit Anleitungen vermischen
Kurzübersicht quantitative Basiswerte
Nachfolgend nur erste Hinweise, die je nach Sprache und Zielgruppe angepasst werden; siehe Prüfliste.
| Dimension | Empfohlener Startwert | Nutzungsgrenze |
|---|---|---|
| Englische Satzlänge | Ab ca. 20 Wörtern auf Verschachtelung achten | Nicht mechanisch auf Chinesisch anwenden, Bedingungen und Verträge nicht zerreißen |
| Absatz | Ein Hauptpunkt pro Absatz | Ausnahmen und Warnungen können beim Originalabsatz bleiben |
| Liste/Schritte | Bei längerer Liste Gruppierung in Betracht ziehen | Nicht um der Anzahl willen vollständige Schritte löschen |
| Passivkonstruktionen | Bei unklarem Subjekt umformulieren | Keinen festen Prozentsatz festlegen, der erreicht werden muss |
| Mermaid | Bei vielen Knoten Übersichts- und Detaildiagramme in Betracht ziehen | Tatsächliche Rendering-Lesbarkeit beurteilen |
| Tabelle | Breite Tabellen in Betracht ziehen, aufteilen oder transponieren | Zum Vergleich notwendige Spalten und Einheiten erhalten |
Zahlen sind Empfehlungen, keine Branchenstandards oder Forschungsergebnisse; Fakten, Verträge, Sicherheits- oder Rechtstexte nicht verändern, um Werte zu erreichen.
Kurzübersicht Antimuster
| Antimuster | Symptome | Lösung |
|---|---|---|
| Almighty Thud | Monströse Dokumentation, alle Informationen gleichgewichtig, wichtige Entscheidungen untergehend | Aufteilen oder Prioritätsstufen hinzufügen |
| Typenvermischung | API-Referenz in Tutorials gepackt, in Referenzen „Warum" geschrieben | Nach Diátaxis trennen |
| Wiederholende Vorworte | Einleitungen ohne substanzielle Informationen | Wortwahl straffen, Risiko- und Schrittinformationen erhalten |
| Synonymwanderung | Dasselbe Feature mit verschiedenen Begriffen | Terminologie vereinheitlichen |
| Unklare Beziehungen | Bedeutung von Verzweigungen oder Pfeilen muss erraten werden | Bei unklaren Beziehungen Labels ergänzen |
| chartjunk | Überflüssige Dekorationslinien, Hintergründe in Tabellen | Dekoration ohne Informationswert entfernen |
| Beispielüberfrachtung | Beispiele für alle Szenarien erschöpfend | Nur die häufigsten Anwendungsfälle behalten |
| Parallele Wartung | Derselbe Fakt wird an mehreren Stellen unabhängig verwaltet | Eine Stelle behalten, restliche durch Links ersetzen |