--- type: resource status: reference title: Schreibstil summary: "Stichpunkte und Tabellen statt Textblöcke, Anleitung und Hintergrund als getrennte Seiten, eine Kommentarzeile je Codeabschnitt — Realität vor Stil, Referenzdokument." tags: [regelwerk, schreibstil, dokumentation] created: 2026-08-24 updated: 2026-09-29 --- # Schreibstil Angeordnet am 2026-08-24, umgestellt auf Pascals Anordnung am 2026-09-29: lange Anleitungen erschlagen den Leser und führen zu Frust. Gilt für alles, was ein Mensch lesen soll: - Technische Anleitungen, Handouts, Bookstack-Artikel, Kundendokumentation - Codedoku unter `docs/code/`, Projektdokumentation - Konzepte, Portfolio-Dokumente, Entscheidungsvorlagen - Sitzungszusammenfassungen und Agentenprotokoll Ausnahmen stehen unten unter „Wo der Stil nicht gilt". ## Der Maßstab - **Kurz, aber vollständig.** Jede Aussage, die der Leser zum Umsetzen braucht, bleibt drin. Gekürzt wird die Verpackung, nie der Inhalt. - **Stichpunkte und Tabellen statt Textblöcke.** Fließtext höchstens zwei Sätze am Stück, danach Liste oder Tabelle. - **Ein Stichpunkt trägt eine ganze Aussage.** Wer, was, unter welcher Bedingung. Kein Stichwort-Telegramm wie „Firewall — beachten". - **Tabellen für alles Vergleichbare:** Optionen, Parameter, Rollen, Zuständigkeiten, Vorher/Nachher. - **Du sprichst zu jemandem.** „Du brauchst dafür", nicht „es wird benötigt". Die Sie-Form nur, wo eine Datei sie verlangt (etwa [[AI/Regelwerk/seo|seo.md]]). - **Zuerst, wofür das gut ist.** Eine Zeile, dann der Weg. - **Wörtlich statt bildhaft.** Sag, was du meinst; gibt es eine wörtliche Formulierung, nimm sie. - **Kein Vortragston.** Keine Einleitung über die Wichtigkeit, kein Fazit, das wiederholt. ## Anleitung und Hintergrund — zwei Seiten Eine technische Anleitung besteht aus zwei Dateien nebeneinander: | | `-anleitung.md` | `-hintergrund.md` | |---|---|---| | Enthält | Zweck (eine Zeile), Link auf den Hintergrund, Voraussetzungen, nummerierte Schritte, Codeblöcke, Prüfen | Link zurück auf die Anleitung, Warum so, Architektur, Fallstricke im Detail, Alternativen, Quellen | | Enthält nicht | Begründungen, Architektur, Historie, Alternativen | die Schrittfolge | | Form | Liste und Code | Stichpunkte und Tabellen, kurze Absätze erlaubt | - In Bookstack: zwei Seiten im selben Kapitel, „ — Anleitung" und „ — Hintergrund". - **Der Fallstrick bleibt am Schritt, an dem man reinläuft** — als eine Zeile mit ⚠. Die Erklärung dazu steht im Hintergrund. - Kurze Anleitungen ohne nennenswerten Hintergrund brauchen keine zweite Seite. Dann fehlt der Link, und es steht nichts Erklärendes in der Anleitung. ## Code in Dokumenten - **Eine Kommentarzeile über jedem Codeblock-Abschnitt**, die sagt, was der Abschnitt tut. - **Keine Zeilenkommentare.** Was ein Schalter bedeutet, steht im Hintergrund. - Ein Block mit mehreren Aufgaben wird in Abschnitte geteilt, jeder mit seiner Kommentarzeile. - Kommentarzeichen der Sprache: `#` für Bash, PowerShell, Python, YAML; `//` für JavaScript und C#; `--` für SQL; `REM` für cmd. - Gilt nur für Code **in Dokumenten**. Produktivdateien folgen [[AI/Regelwerk/codedoku|codedoku.md]]. ## Weitere Dokumentarten | Dokumentart | Form | |---|---| | Codedoku `docs/code/` | vier Fragen aus [[AI/Regelwerk/codedoku|codedoku.md]] als Überschriften, darunter Stichpunkte; Ablauf als nummerierte Liste | | Konzept, Portfolio, Entscheidungsvorlage | Tabellen und Stichpunkte; eine Empfehlung steht mit ihrem Grund in derselben Zeile | | Sitzungsbericht, Agentenprotokoll | Stichpunkte je Thema: was erledigt, was offen, was Pascal tun muss | ## Die Grenze — Realität vor Stil Die Form ändert sich, die Aussagen nicht. Vier Regeln ohne Ermessensspielraum: 1. **Nichts erfinden.** Keine Zahlen, Versionsnummern, Pfade oder Fehlermeldungen aus dem Gedächtnis. Konkretheit kommt aus der Quelle oder gar nicht. 2. **Nichts weichzeichnen.** Gilt eine Aussage nur unter einer Bedingung, bleibt die Bedingung im Stichpunkt — auch wenn er dadurch lang wird. Kürzen heißt nicht, Bedingungen zu streichen. 3. **Lücken benennen, nicht überbrücken.** „Unter Rocky 10 nicht geprüft" ist ein Ergebnis und bekommt einen eigenen Stichpunkt. 4. **Keine Position, die das Material nicht hergibt.** Eine Empfehlung braucht einen Grund, der danebensteht. Der Grund für die Härte: Kürzen und Glätten haben dieselbe Fehlerart — Bedingungen und Vorbehalte fallen weg, weil sie sperrig sind. Vermenschlichen hat eine zweite: Es erfindet Konkretheit, damit der Text weniger nach Modell klingt. Am Ende steht jemand vor einem System, das anders reagiert als beschrieben. ## Vorher / Nachher | Statt | Besser | |---|---| | Absatz aus fünf Sätzen über Voraussetzungen | Liste „Voraussetzungen", ein Punkt je Voraussetzung | | „Im Anschluss erfolgt die Konfiguration des Dienstes." | „3. Dienst konfigurieren:" plus Codeblock | | Codeblock mit Kommentar an jeder Zeile | eine Kommentarzeile je Abschnitt; Schalter im Hintergrund erklärt | | „Es ist zu beachten, dass unter Umständen Probleme auftreten können." | „⚠ Auf Windows-Konsolen bricht das bei Umlauten in der Ausgabe ab (cp1252)." | | „Firewall beachten" | „Port 443 eingehend muss am Perimeter offen sein, sonst schlägt die Registrierung fehl." | | „Best Practice ist X." | Tabellenzeile: Option X — nehme ich, weil Y; Option Z — ginge, kostet W | | „Diese Lösung bietet zahlreiche Vorteile." | Streichen. Gibt es Vorteile, je Vorteil ein Stichpunkt; sonst war der Satz leer. | | „Studien zeigen, dass …" | Quelle nennen oder Behauptung streichen. | | „Der Prozess ist nun abgeschlossen." | Streichen. | ## Das Referenzdokument Ton per Beispiel, nicht per Beschreibung — dieselbe Regel wie bei den Dokumentations-Großprojekten. Jeder Subagent, der Dokumente schreibt, bekommt dieses Paar mit: ````markdown ### Tote Links im Vault finden — Anleitung Zeigt alle Wikilinks, die ins Leere zeigen. Warum so: [[tote-links-finden-hintergrund|Hintergrund]] **Voraussetzungen** - Python ist unter dem Befehl `python` erreichbar. - Du stehst im Vault-Root. **Schritte** 1. Linkcheck starten: ```bash # Linkcheck über den ganzen Vault, Ausgabe in UTF-8 PYTHONIOENCODING=utf-8 python .vault-tools/linkcheck/linkcheck.py --vault . ``` ⚠ `python3` startet hier den Microsoft-Store-Stub und läuft nicht. 2. Gemeldete Links in den genannten Dateien korrigieren. **Prüfen** - Ein zweiter Lauf meldet die korrigierten Links nicht mehr. - Pfade in Backticks prüft der Linkcheck nicht — die siehst du von Hand durch. ```` ````markdown ### Tote Links im Vault finden — Hintergrund - **Warum der Linkcheck:** Er lässt Codeblöcke aus. Der `vault_doctor` aus dem alten Toolkit tut das nicht und fand dort 92 tote Links, keiner davon echt — etwa `[[ $EUID -eq 0 ]]` aus einem Bash-Beispiel. - **Warum `PYTHONIOENCODING=utf-8`:** Ohne die Variable zerlegt die Windows-Konsole die Umlaute in der Ausgabe. - **Warum `python`:** `python3` meldet auf dieser Maschine „Python was not found". - **Blinder Fleck:** Wer `AI/sessions/…` in Backticks statt `[[AI/sessions/…]]` schreibt, hat einen Verweis, den keine Prüfung kontrolliert. Zur Anleitung: [[tote-links-finden-anleitung|Anleitung]] ```` Woran man den Stil erkennt: - Die erste Zeile sagt, wofür das Ding gut ist. - Die Anleitung enthält keinen einzigen Begründungssatz, nur den ⚠-Hinweis am Schritt. - Jede Aussage des Hintergrunds ist ein Stichpunkt mit fettem Stichwort. - Die Stelle, die das Werkzeug nicht sieht, wird benannt. ## Bestehende Anleitungen umbauen - Neue Dokumente entstehen im neuen Stil. Der Bestand bleibt, bis jemand ihn anfasst. - Umbau auf Zuruf mit dem Skill `anleitung-straffen` (`.claude/skills/anleitung-straffen/`). - **Beim Umbau behält die bestehende Datei ihren Namen und Titel und wird die Anleitung.** Grund: Wikilinks und die Bookstack-Zuordnung zeigen auf sie. Neu daneben entsteht `-hintergrund.md` mit Titel „ — Hintergrund". ## Verhältnis zum `humanizer`-Skill - Diese Datei ist die **Voreinstellung**. - Der `humanizer` ist der **Nachbearbeitungsgang** für Texte, die schon glatt geraten sind und nach Modell klingen. Er misst die Satzlängen-Varianz (`scripts/rhythmus.py`), kennt die deutschen KI-Marker und hat dieselbe Regel „Nichts erfinden". - Ihn rufen, wenn ein fertiger Entwurf nach Modell klingt oder ein Kundendokument den letzten Schliff braucht — nicht als Ersatz für sauberes Schreiben. - **Der humanizer kennt diese Datei nicht.** Er rät, Aufzählungen zu entkalibrieren, sparsam zu fetten und Listen mit fettem Stichwort und Doppelpunkt in Prosa aufzulösen — genau die Hintergrund-Form dieser Datei. Nach seinem Durchgang prüfst du: Listen und Tabellen sind Listen und Tabellen geblieben, die fetten Stichwörter im Hintergrund stehen noch. ## Nur für Claude Fable 5.1 Schreibt Fable 5.1 den Text, kommen drei Punkte aus [[AI/Regelwerk/fable-5-1|fable-5-1.md]] dazu (Abschnitte 5, 6, 7): - Die Prosa neigt zu langen, dichten Sätzen — hier also erst recht Liste statt Absatz. - Im Chat greift es seltener zu Listen als frühere Modelle — bei vielgliedrigem Inhalt trotzdem Liste oder Tabelle. - Beim Zusammenfassen übernimmt es Quellwortlaut eher unmarkiert — als Zitat kennzeichnen oder in eigenen Worten. Andere Modelle entscheiden selbst, ob sie das übernehmen; die Regeln dieser Datei gelten für alle. ## Wo der Stil nicht gilt Dort bleibt die Form, die das Dokument verlangt: - **Regelteile von ISMS- und Compliance-Dokumenten.** Eine Anforderung wird zitiert, nicht umformuliert. „Muss" und „darf nicht" bleiben. Basis- und Zusatzkriterien bleiben getrennt und gekennzeichnet. - **Prüfprotokolle, Nachweise, Abnahmedokumente** — alles, was jemand später gegen uns hält. Was gemessen wurde, mit welchem Befehl, mit welchem Ergebnis. - **Kopfkommentare von Prüfskripten.** Geltungsbereich und benannte Lücken — siehe [[AI/Regelwerk/pruefwerkzeuge|pruefwerkzeuge.md]]. - **Rechtliche und vertragliche Texte.** Präzision schlägt Kürze. Der **umgebende** Text — Einleitung, Begründung, Handlungsempfehlung — steht trotzdem in diesem Stil. ## Referenzen - [[CLAUDE|↑ Claude.md (Stamm)]] - [[AI/Regelwerk/codedoku|codedoku.md]] — Kommentare in Produktivdateien, Codedoku - [[AI/Regelwerk/dokumentations-grossprojekte|dokumentations-grossprojekte.md]] — Referenzdokument bei Fan-Out - [[AI/Regelwerk/pruefwerkzeuge|Prüfwerkzeuge]] - [[AI/Regelwerk/fable-5-1|fable-5-1.md]] — nur für Fable 5.1: Schreibdichte, Formatierung, Zitieren