Qualität von Entscheidungs-/Optionsdokumenten
Verwende diese Regeln für jede Engineering-Entscheidung, jeden Spike oder jedes Optionsdokument, das Optionen und eine Empfehlung vorschlägt. Der Leser ist ein vielbeschäftigtes Teammitglied ohne Kontext; das Dokument muss überfliegbar, einfach und nachweisbar sein.
Zielgruppe: null Kontext annehmen
- Nimm an, dass der Leser keinerlei informelles Wissen kennt. Erkläre oder verlinke jeden Begriff, jedes Akronym, jeden Dienstnamen, jedes Tool und jedes verwendete Muster (z. B. CDC, Debezium, Kafka, SNS, SQS, Outbox, logische Replikation, Temporal). „Niemand weiß, was das alles bedeutet.“
- Erkläre, was eine Sache ist und tut, in einfachen Worten, bevor du dich darauf stützt. Bevorzuge eine schlichte Phrase + einen Link gegenüber Fachjargon allein.
- Füge keinen separaten Glossarabschnitt hinzu, es sei denn, danach gefragt; verlinke Begriffe stattdessen direkt im Text.
Schreibstil
- Beginne mit dem Kern der Sache (BLUF). Nenne die wichtigste Erkenntnis zuerst, dann die Details.
- Kurz. Einzeiler schlagen Absätze. Wenn ein Abschnitt wie eine Textwand wirkt, streiche ihn. Niemand liest lange Dokumente.
- Einfache Sprache. Kein KI-Geschwurbel, kein Füllmaterial, das „gut klingt“, keine Erzählung der eigenen Entstehungsgeschichte des Dokuments, keine Verteidigung deiner Argumente im Dokument (z. B. niemals „direkter Beweis, nicht Theorie“).
- Keine Em-Dashes (Gedankenstriche) irgendwo. Keine GROSSSCHREIBUNG zur Betonung (verwende Fettdruck). Keine dekorativen Nummerierungen oder Mittelpunkt-Trennzeichen, die wie maschinengeneriert wirken.
- „Wir“ für die Arbeit, die das Team erledigen würde; „Ich“ für die Meinung/Neigung des Autors. Halte sie getrennt.
Struktur
- Empfehlung / TL;DR vorne. Ein paar Zeilen: die Neigung, die Hauptgründe (als Aufzählungspunkte), formuliert als erste Einschätzung in einem lebendigen Dokument, das sich nach Team-Feedback ändern wird. Mache Gleichgültigkeit und Flexibilität explizit, wenn sie real sind; nenne trotzdem eine Präferenz und begründe sie.
- Ein einklappbarer Block (Toggle) pro Option. Die eingeklappte Zeile zeigt eine kurze Bezeichnung + einen einzeiligen, verständlichen Kern in einfachem Englisch. Im Inneren: ein einfaches Diagramm, Funktionsweise, was wiederverwendet wird (mit Nachweis-Links), was neu ist, Skalierung/Kompromiss und ein kleiner Code- oder Konfigurationsentwurf. Halte die Oberfläche überfliegbar.
- Halte Parallelabschnitte parallel (Konsistenz ist keine Option). Optionen/Tools/Kandidaten sind Geschwister, daher MUSS jeder dem gleichen Template folgen: die gleichen Unterabschnittsüberschriften in der gleichen Reihenfolge, das gleiche Vorhandensein von Diagramm / Medien / Code-Entwurf, die gleiche Tiefe. Lege das Template einmal fest (ausgehend vom stärksten Abschnitt) und wende es auf alle an; wenn du einen Abschnitt hinzufügst oder bearbeitest, passe die anderen an. Lasse niemals zu, dass jeder Abschnitt in seine eigene Form abdriftet – eine abweichende Struktur wirkt schlampig und macht den ganzen Zweck (einfacher Seitenvergleich) zunichte. Dies ist ein wiederkehrendes Fehlermuster: Überprüfe es vor dem Teilen.
- Gruppiere Optionen entlang einer einzigen, sauberen Achse (z. B. wann etwas passiert oder wie). Vermische niemals zwei Achsen in einer Gruppierung oder erstelle falsche Peer-Kategorien, die sich überschneiden. Wenn etwas ein Implementierungsdetail einer anderen Option ist (ein Ausführer, ein Ablageort), integriere es, liste es nicht als gleichrangig auf.
- Veranschauliche den gemeinsamen/schwierigsten Kern, nicht nur die Optionen, mit einem eigenen Entwurf (behandle den gesamten Lebenszyklus, z. B. Erstellen/Aktualisieren und Löschen).
- Diagramme (Mermaid) zur Veranschaulichung; halte sie genau (zeichne keine Tabelle als separate Datenbank usw.).
- Beende mit einer Einladung zum Feedback („Andere Ideen?“); höre niemals abrupt auf.
- Halte Metadaten minimal, nur was gewünscht wird (oft nur der Ticket-Link). Lasse Status-/Standardzeilen weg, die den Autor nicht interessieren.
Vollständigkeit der Optionen
- Liste Optionen erschöpfend auf, nicht nur die üblichen zwei oder drei. Echte Probleme haben viele; schließe auch die offensichtlich schlechten ein, damit das gesamte Feld sichtbar ist (kennzeichne sie als schwach/Baseline).
- Erwähne immer die „Nichts tun“-Baseline und nenne ihre Konsequenz.
- Recherchiere echte Quellen (Dokumentation, Stack Overflow, Reddit, Anbieter-/Musterreferenzen), um Optionen und die korrekte Terminologie zu finden. Wikipedia allein ist der faule Standard; finde die relevante Primärquelle.
- Benenne etablierte Entwurfsmuster korrekt und verlinke sie; wende kein falsches Muster an. Überprüfe, ob das Muster tatsächlich passt, bevor du es zitierst.
Nachweise (die Kernregel)
- Jede Behauptung darüber, was das System bereits hat, wird durch einen Hyperlink zum Beweis untermauert (Quelldatei + Zeile, Infra-Konfiguration, Ticket). Keine Annahmen, kein Herumreden.
- Wenn eine Behauptung nicht durch einen Link belegt werden kann, kennzeichne sie als „unbestätigt“, anstatt sie als Tatsache darzustellen.
- Überprüfe durch Lesen der tatsächlichen Datei/Infrastruktur selbst. Behandle die Feststellung eines Sub-Agenten nicht als Tatsache, ohne sie gelesen zu haben; unterscheide „Ich habe es gelesen“ von „Ein Agent hat es gemeldet“ und gib die Vertrauenswürdigkeit an, wenn es darauf ankommt.
- Wechsle niemals stillschweigend die Position. Wenn eine Überprüfung eine frühere Behauptung ändert, sage, was falsch war und warum, und korrigiere es.
- Hinterfrage die Prämisse und deine eigenen Schlussfolgerungen, wenn Druck ausgeübt wird; überprüfe neu, anstatt zu verteidigen.
- Verlinke jede Kennung, jeden Dateinamen, jedes Ticket, jeden PR und jede Referenz; hinterlasse niemals eine nackte ID, die der Leser suchen muss.
Inhalt des Optionsdokuments
- Trenne den harten gemeinsamen Kern (die Arbeit, die unabhängig von der Option nötig ist) von den Hüllen/Mechanismen darum herum und sage, was der tatsächliche Aufwand und das Risiko ist.
- Gib Vor- und Nachteile, fundiert. Übertreibe nicht („der meiste Aufwand und fast das gesamte Risiko“ → abschwächen auf das, was zutrifft).
- Notiere, was jede Option wiederverwendet (das bereits existiert) im Vergleich zu dem, was neu ist.
Prozess
- Mache minimale, gezielte Änderungen. Schreibe nicht das gesamte Dokument für eine kleine Änderung um.
- Bei sensiblen Formulierungen zeige den Entwurf im Chat und iteriere, bevor du ihn anwendest.
- Für eine begleitende Review-/Slack-Nachricht: halte sie extrem kurz und wirklich einladend (Menschen sind beschäftigt und werden sie nicht lesen wollen); behaupte nicht, dass es dringend oder nicht dringend ist, es sei denn, du wirst gefragt; richte die Prüfer mit dem einen nützlichsten Rahmen ein.
Abschlussprüfung
Vor dem Teilen eines Dokuments überprüfen:
- Die Hauptaussage / Empfehlung steht vorne und ist kurz.
- Jede „Was wir haben“-Behauptung hat einen Nachweis-Link; unbestätigte Behauptungen sind gekennzeichnet.
- Fachjargon ist erklärt oder verlinkt; ein Leser ohne Kontext kann folgen.
- Optionen sind entlang einer sauberen Achse gruppiert, jeweils einklappbar mit einer einzeiligen Zusammenfassung.
- Keine Em-Dashes, keine GROSSSCHREIBUNG zur Betonung, keine Selbsterzählung, kein KI-Geschwurbel.
- „Wir“ vs. „Ich“ korrekt verwendet; Neigung klar angegeben, aber Flexibilität deutlich.
- Das Dokument lädt zu Feedback ein und endet nicht abrupt.