Wie man gute Design-Dokumente schreibt

• Ein Design-Dokument ist ein technischer Bericht, der die Implementierungsstrategie, Einschränkungen und Trade-offs eines Systems zusammenfasst.
• Ein Design-Dokument dient dazu, die Leserschaft davon zu überzeugen, dass das jeweilige Design für die gegebene Situation geeignet ist.
• Die Struktur des Dokuments ist wichtig, und durch einen logischen Fluss sollte vermieden werden, dass die Leserschaft vom Inhalt überrascht wird.
• Durch Redigieren ist es nötig, unnötige Wörter zu streichen und so die Aufmerksamkeitsressourcen der Leserschaft zu schonen.
• Die Nutzung kurzer Absätze und von Anhängen sowie die Verbesserung der Schreibkompetenz durch Übung sind wichtig.

---

Definition

• Ein Design-Dokument ist ein technischer Bericht, der die Strategie zur Systemimplementierung im Kontext von Trade-offs und Randbedingungen zusammenfasst.

Ziel

• Wie ein Beweis in der Mathematik einen Satz nachvollziehbar macht, soll ein Design-Dokument die Leserschaft davon überzeugen, dass dieses Design optimal ist.
• Schon das Schreiben selbst erhöht die Strenge des Denkens im Designprozess.
• Beim Schreiben eines Design-Dokuments lassen sich vage Gedanken in konkretes Denken überführen.

Organisation

• Die Struktur eines guten Design-Dokuments ist genauso wichtig wie die Organisation von Code.
• So wie Anfänger Code schreiben, neigen viele dazu, „Spaghetti-Design-Dokumente“ zu verfassen.
• Werden Sätze ohne logische Reihenfolge aneinandergereiht, fällt es der Leserschaft schwer, dem Kontext zu folgen, und es entsteht Verwirrung.
• Ein perfektes Dokument sollte einen natürlichen Fluss haben, ohne die Leserschaft zu überraschen; jeder Satz sollte sich selbstverständlich auf das Vorherige stützen.
• Ziel ist es, den Denkzustand der Leserschaft zu erfassen und sie schrittweise in einen neuen Zustand zu führen.
• Vorhersehbare Einwände sollten im Voraus ausgeräumt werden; Erklärungen sollten kommen, bevor die Leserschaft Gegenargumente formuliert.

Redigieren

• Nachdem der Inhalt gut organisiert ist, wird die Phase des Entfernens unnötiger Wörter (Redigieren) wichtig.
• Die Aufmerksamkeit der Leserschaft ist eine begrenzte Ressource, daher sollte unnötige Information konsequent gelöscht werden.
• In einem Entwurf lassen sich bedeutungslose Formulierungen oft um etwa 30 % reduzieren.
• Wer die Dokumente anderer mit kritischem Blick redigiert, kann auch eigene Texte effizienter überarbeiten.
• Auch das Üben mit kurzen Tweets (280-Zeichen-Limit) hilft dabei, Gedanken zu vereinfachen und die Fähigkeit zur Verdichtung zu verbessern.

Erfahrung und Übung

• Es gibt keinen besseren Weg, die eigenen Fähigkeiten zu verbessern, als wiederholte Übung.
• Die Erfahrung mit einer dokumentenzentrierten Kultur bei Amazon hat stark zur Verbesserung der Schreibkompetenz beigetragen.
• In wichtigen Meetings werden Design-Dokumente im Umfang von 1 bis 6 Seiten verteilt; anschließend lesen alle still und notieren Kommentare am Rand.
• Durch Feedback lässt sich die Schreibfähigkeit ganz konkret verbessern.

Konkrete Tipps

Kurze Absätze verwenden

• Ein Design-Dokument sollte seinen Fluss durch aufeinanderfolgende prägnante Bullet Points aufbauen.
• Jeder Bullet Point (Beobachtung, Idee, Problem, Verbesserung usw.) sollte aus einem kurzen Absatz bestehen, der sich auf ein Konzept konzentriert.
• Jeder Absatz sollte so klar sein, dass er sich in einem Satz zusammenfassen lässt; so werden die Kurzzeitgedächtnis-Ressourcen der Leserschaft geschont.

Anhänge nutzen

• Komplexe Berechnungen oder Simulationsergebnisse sollten nicht im Haupttext, sondern ausführlich in einem Anhang dokumentiert werden; im Haupttext reicht eine kurze Erwähnung in Form einer Fußnote.
• Für das Verständnis der zentralen Schlussfolgerungen des Haupttexts ist der Anhang nicht zwingend erforderlich; er wird für interessierte Leser bereitgestellt.

Beispiel für Redigieren

• (Vor dem Redigieren, weitschweifiger Absatz):

  Jeder Bullet Point sollte im Dokument ein eigener Absatz sein. Jeder Absatz sollte sich in einem Satz zusammenfassen lassen. Er muss nicht tatsächlich nur aus einem Satz bestehen; zur Erklärung eines Konzepts können zusätzliche Erläuterungen nötig sein. Aber nachdem die Leserschaft ihn gelesen hat, sollte sie ihn in einem Satz zusammenfassen können.

• (Nach dem Redigieren, gestraffter Absatz):

  Jeder Bullet Point sollte ein Absatz sein, der sich in einem Satz zusammenfassen lässt. Er muss nicht tatsächlich nur aus einem Satz bestehen, und bei Bedarf können zusätzliche Erläuterungen ergänzt werden. Aber nach dem Lesen sollte er sich auf einen Satz verdichten lassen.

Abschluss

• Ein Design-Dokument ist ein wichtiger Prozess, in dem sich die eigenen Fähigkeiten durch Strenge im Denken, logischen Fluss, leserzentriertes Redigieren und wiederholte Übung weiterentwickeln lassen.

[GN⁺]

Hacker-News-Kommentar

• Der Kommentar stellt zwei Zitate aus dem Artikel vor, die besonders Eindruck gemacht haben. Das erste stammt aus einem Screenshot auf X: „Im Prozess des Schreibens werden Ideen 10-mal besser.“ Das zweite steht gleich am Anfang: „Die wichtigste Person, die man überzeugen muss, ist der Autor selbst.“ Es überrascht, dass es selbst nach vielen Jahren in der Branche noch Menschen gibt, die sich gegen die Notwendigkeit von Design-Dokumenten stellen. Leslie Lamport sagte einmal, „Schreiben ist die Art der Natur, uns zu zeigen, wie schlampig unser Denken ist“. Wer seine Fähigkeiten im technischen Schreiben weiter ausbauen möchte, dem wird der Artikel Write Like an Amazonian(https://medium.com/@apappascs/…) empfohlen
  • Vielleicht weil sich der Rat „Verwandle Adjektive in Daten“ in der gesamten Tech-Branche verbreitet hat, sind Lebensläufe heute oft so voll mit Zahlen, dass man kaum noch weiß, was sie eigentlich bedeuten
• Als Design-Reviewer gibt es etwas, das jeder Verfasser von Dokumenten unbedingt verinnerlichen sollte: „Ein gutes Dokument vermittelt dem Leser das Problem und das Denkmodell so, dass die Lösung, die nach wochenlangem Nachdenken entstanden ist, beim eigentlichen Vorstellen ganz natürlich Zustimmung findet.“ Das Lieblingszitat dazu ist: „Hätte ich mehr Zeit gehabt, hätte ich einen kürzeren Brief geschrieben.“ Ein Design-Dokument sollte Komplexes vereinfachen und ist nicht der Ort, um wahllos alle Umwege und Fehlschläge aufzunehmen, die ein Entwickler erlebt hat. Solche Inhalte können natürlich ebenfalls wertvoll sein, sollten dann aber besser in einem separaten Dokument oder im Anhang landen. Wichtig ist, den Weg nach vorn einfach zu zeigen
  • Die Formulierung „mehr Zeit, kürzerer Brief“ gefällt besser
  • Es werden sich immer wieder diese Fragen gestellt: „Wird zu diesem Thema unnötiger Streit entstehen?“ und „Ist dieser Streit es wert?“ Das Ziel ist, dass neue Leser ohne große Hürden in die Diskussion einsteigen können und bei unwichtigen Punkten gar keine Kontroversen entstehen
• Amazon-Meetings beginnen damit, dass der Präsentierende ein in Prosa geschriebenes Dokument austeilt. Alle sitzen still da, lesen es und machen mit rotem Stift Notizen und Fragen an den Rand. Zwar wurde nicht tatsächlich bei Amazon gearbeitet, aber diese Methode wirkt erstaunlich effektiv, und Menschen, die davon aus eigener Erfahrung berichten, scheinen sie durchweg zu mögen. Auf den ersten Blick wirkt es ineffizient, wertvolle Meeting-Zeit damit zu verbringen, gemeinsam nur zu lesen. Würden jedoch alle vorher lesen und sich vorbereiten, könnten Meetings natürlich kürzer sein. Gleichzeitiges Lesen in Echtzeit führt dazu, dass man auf langsame Leser wartet oder dass wegen unterschiedlicher Vorkenntnisse und fehlenden Kontexts alle etwas diffus Zeit verstreichen lassen. Bei Design-Reviews bei Google wurde oft beobachtet, dass die meisten Teilnehmer unvorbereitet zum ersten Mal das Dokument sehen und trotzdem direkt diskutieren. Das lag wohl daran, dass Google keine starke Dokumentenkultur hatte und Team Leads oder Manager stillschweigend akzeptierten, unvorbereitet zu erscheinen. Schon eine Kultur, in der vor dem Meeting zuverlässig gelesen wird, könnte die Meeting-Zeit deutlich effizienter machen
  • Oft heißt es, Vorablektüre verkürze Meetings, aber die Praxis bei Amazon ist eine Reaktion auf die Realität, dass Menschen eben nicht wirklich im Voraus lesen. In einem älteren Artikel dazu hieß es, eine starke Kultur der Vorbereitung vorab sei praktisch unmöglich gewesen. Jeder Teilnehmer konnte sich vorher nicht vorbereiten, weil direkt davor noch ein anderes Meeting lag, und davor wiederum das nächste. Theoretisch kann man kritisieren, man müsse dann eben die Zahl der Meetings reduzieren, aber in der Praxis waren die Meetings wertvoll, und selbst inklusive Lesezeit wurden ausreichend Entscheidungen getroffen. Am Ende kommt es auf die Ergebnisse an, und offenbar überwiegen bei Amazon die Vorteile dieser Methode ihre Nachteile
  • Es wird infrage gestellt, warum es wichtig sein soll, wann genau das Dokument gelesen wird. Wenn mehr Zeit nötig ist, könne man das Meeting einfach verlängern. Ein Nachteil sei höchstens, dass sich längere Meetings schwerer terminieren lassen, aber am Gesamtzeitaufwand ändere das nichts
  • Es wird vermutet, dass mehr Zeit verloren geht, wenn nicht alle auf demselben Verständnisstand sind oder jemand befürchtet, einen Corner Case zu übersehen
  • Es wird von der Erfahrung berichtet, dass schlicht nichts passiert, wenn etwas nicht tatsächlich im Meeting behandelt wird
• Es gibt viel hervorragenden Rat zu Klarheit und Redigieren. Die Schwäche liegt darin, was nach der Freigabe mit dem Dokument geschieht. Ohne Pflege verfällt es zum Zustand der „Design-Archäologie“. Andrew Harmel-Law schlug vor einigen Jahren Architecture Decision Records (ADRs) als wirksame Methode vor, Architekturentscheidungen innerhalb einer Organisation festzuhalten, und das könnte helfen. ADRs liegen neben dem Code, zum Beispiel adr/001-use-postgres.md, und halten Kontext, Entscheidung und Status kurz fest. Der Vorteil ist, dass sie sich bei jedem PR leicht mitprüfen lassen und bei veränderten Umständen einfach ersetzt werden können. Auch die ursprüngliche Begründung einer Entscheidung bleibt noch Monate später auffindbar. [Link: https://martinfowler.com/articles/…]
  • Es wird gefragt, ob in so einem Modell Gremien aus Bereichen wie Security, Privacy und Compliance dann bei jedem PR mit ADRs als Reviewer eingebunden werden. Zweifel werden geäußert, dass solche PRs dann innerhalb von 90 Tagen gemergt werden könnten
  • Der Link auf MF.com(https://thoughtworks.com/radar/techniques/…) müsste eigentlich vollständig gelesen werden, aber der „Advice Process“ endet im Grunde bei „Sprich mit allen“. Menschen mit dem Titel „Managing“ dürften an diesem Punkt das Interesse verlieren. Der eigentliche Kern scheinen die „vier unterstützenden Elemente“ zu sein. Beim Versuch, mehr über ADRs zu erfahren, wurde dieser Link geöffnet und am Ende nur ein PDF(https://thoughtworks.com/content/dam/…) heruntergeladen. Eine klare Definition dessen, was ADRs tatsächlich sind, wäre hilfreich
  • Session messenger ist ein typisches Beispiel. Dort gab es so viele Design- und Architekturänderungen, dass es keine autoritative Quelle mehr gibt, die offiziell erklärt, wie alles funktioniert. Und wenn sichere Nachrichten gebraucht werden, sollte man einfach Signal verwenden
• Nach dieser Erfahrung sind Organisation und Klarheit die größten Hindernisse dafür, dass Softwareingenieure bessere Dokumente schreiben. Die Metapher des Autors vom „Code-Spaghetti“ ist ein gutes Beispiel dafür, wie wichtig die Organisation von Ideen ist. Etwas Ähnliches wurde selbst schon einmal anders zu vermitteln versucht, aber künftig soll diese Metapher verwendet werden. Es wurde auch früher schon ein ähnlicher Blogpost geschrieben(https://ryanmadden.net/things-i-learned-at-google-design-docs/), und die Gemeinsamkeiten wie Informationsdichte und die Bedeutung von Praxis sowie die Unterschiede zwischen Unternehmen waren interessant. Bei der These von den „kurzen Absätzen“ gibt es leichte Vorbehalte. Kurze Absätze entstehen erst durch gut zugerichtete Information; bloß Zeilenumbrüche einzufügen hilft nicht. Der Abschnitt „Editing“ erklärt diese zugrunde liegende Idee besser
• Es gibt einen eigenen Prozess beim Schreiben. Schritt 1: Alles, was einem einfällt, ungeordnet in ein Dokument kippen, gern auch per Diktat. Schritt 2: Ein LLM (Large Language Model) versuchen lassen, Struktur und Fluss hineinzubringen. Tatsächlich kann das Ergebnis an dieser Stelle auch verworfen werden; der Denkprozess läuft weiter. Schritt 3: Mithilfe des LLM-Ergebnisses oder mit einer komplett neuen Gliederung den ersten Entwurf schreiben. Schritt 4: Wörter streichen, einfachere Wörter wählen und alles so knapp wie möglich machen. Schritt 5: Schritt 4 wiederholen. Das LLM dient als Brücke, um einen chaotischen Rohentwurf zu strukturieren. Man muss bereit sein, das vom LLM Produzierte wegzuwerfen. Mindestens 30 % lassen sich immer kürzen. Es ist jedes Mal erstaunlich zu sehen, dass beim Kürzen keine Bedeutung verloren geht
  • Das erneute Redigieren des eigenen Textes fühlt sich genauso wichtig an wie das erste Schreiben. Dabei wird sichtbar, wo vorschnell Schlüsse gezogen wurden und was nicht bedacht wurde. Viele Menschen scheinen Schreiben nicht hoch genug als Werkzeug zur Fokussierung des Denkens zu bewerten. Bei Code ist es ähnlich. Selbst wenn nur ein schlichtes Template geschrieben wird, kommen beim Schreiben von Tests oft Ideen auf, wie sich der Hauptcode verbessern lässt. Aber ein LLM weist einen nicht auf diese qualitativen Verbesserungsmöglichkeiten hin
  • Es ist ein wiederholtes Erweitern, Kürzen, Verdichten, wieder Erweitern und wieder Verdichten. Wenn jemand konkrete Fragen stellt, wird wieder erweitert, und am Ende wird mit einem LLM noch eine lockere Zusammenfassung zum Spaß erstellt. Im Grunde fährt man auf einer endlosen Achterbahn
• Es entsteht der Eindruck, dass mehr geschrieben werden sollte. Zwei bevorzugte Methoden zur Dokumentstruktur sind B.O.O. und Good Strategy/Bad Strategy. B.O.O. steht für Background, Objective, Overview und beschreibt, wie man bis hierher gekommen ist und was wie verändert werden soll. Good Strategy/Bad Strategy ist ein Buch, das aus Diagnose, Leitlinie/Prämissen/Anforderungen und Aktionen besteht und in der Dokumentorganisation B.O.O. ähnelt. B.O.O. passt gut zu Google oder zu Organisationen mit kleineren Teams, während Good Strategy/Bad Strategy für deutlich mehr Größenordnungen taugt, aber einen schreibstarken Autor benötigt
• Durch einen Kurs in technischem Schreiben hat sich die Fähigkeit, Kernaussagen klar zusammenzufassen, stark verbessert. Der Fokus lag auf der Methode „mit dem Rotstift kürzen“: schreiben, durchstreichen, neu schreiben. Dabei wird betont, Konzepte mit möglichst wenigen Wörtern zu vermitteln. Der Prozess besteht aus mehreren Stufen und wird mit Übung immer leichter. Diese Fähigkeit wird auch mit Teammitgliedern geteilt, wobei stets daran erinnert wird, dass es sich um eine Fertigkeit handelt, die regelmäßig trainiert werden muss
• Solche Dokumente und die dazugehörige Schreibkultur werden sehr geschätzt. Gleichzeitig wurde auch gesehen, dass dieser Ansatz nach hinten losgehen kann. Um zu erklären, warum und mit welcher Logik man zu einer Schlussfolgerung gelangt, ist diese Form für überzeugende Dokumente sehr effektiv. Aber nicht immer braucht es genau diese Art von Überzeugungsarbeit. Manchmal ist es für Leser, besonders für solche, die dem Verfasser vertrauen, besser, die Schlussfolgerung direkt zuerst zu lesen. Häufig wollen Leser den Kernpunkt zuerst kennen, statt sich beim Nachvollziehen der Logik zu ermüden. Wenn die Schlussfolgerung erst einmal klar ist, steigt oft auch die Bereitschaft, anschließend die Details nachzuverfolgen
  • Eine Struktur mit einer Zusammenfassung oben und den Details sowie der Begründung darunter funktioniert ebenfalls völlig gut
• Manchmal werden Design-Dokumente direkt für den Fall geschrieben, dass sie am Ende vielleicht nur von einem selbst gelesen werden. Schon das bloße schriftliche Festhalten wirkt sehr kraftvoll. Konkrete Beispieldokumente wären dabei sehr hilfreich, weil es interessant wäre, die eigene Struktur mit den finalen Strukturen anderer zu vergleichen