Googles Kultur des Schreibens von Design Docs (2020)

• Design Docs sind eines der Kernelemente von Googles Software-Engineering-Kultur: relativ informelle Dokumente, die die Hauptautorinnen und -autoren eines Softwaresystems oder einer Anwendung verfassen, bevor sie mit einem Coding-Projekt beginnen
  • Sie dokumentieren eine High-Level-Implementierungsstrategie und wichtige Designentscheidungen und legen den Schwerpunkt insbesondere auf die Trade-offs, die bei diesen Entscheidungen berücksichtigt wurden
  • Die Aufgabe von Softwareingenieurinnen und -ingenieuren ist nicht, Code zu schreiben, sondern Probleme zu lösen; unstrukturierter Text wie ein Design Doc kann in frühen Projektphasen ein prägnanteres und leichter verständliches Werkzeug zur Problemlösung sein als Code

Die Rolle von Design Docs im Softwareentwicklungs-Lebenszyklus

• Zusätzlich zur ursprünglichen Dokumentation des Softwaredesigns erfüllen sie folgende Funktionen:
  • Designprobleme früh identifizieren, solange Änderungen noch günstig sind
  • Im Unternehmen Konsens über das Design herstellen
  • Sicherstellen, dass Cross-Cutting Concerns berücksichtigt werden
  • Wissen erfahrener Ingenieurinnen und Ingenieure in die Organisation tragen
  • Die Grundlage für das organisatorische Gedächtnis zu Designentscheidungen bilden
  • Als zusammenfassendes Artefakt im technischen Portfolio von Softwaredesignerinnen und -designern dienen

Die Struktur eines Design Docs

• Da ein Design Doc ein informelles Dokument ohne strenge Inhaltsrichtlinien ist, gilt als Regel, es in der Form zu schreiben, die für das jeweilige Projekt am besten geeignet ist
  • Context and scope: Gibt einen Überblick über den Hintergrund, vor dem das neue System entsteht, und darüber, was tatsächlich gebaut wird
  • Goals and non-goals: Listet die Ziele des Systems und das auf, was nicht zu seinen Zielen gehört
  • The actual design
    • System-context-diagram: Ein Diagramm, das das System als Teil einer größeren technischen Umgebung zeigt
    • APIs: Ein Entwurf der APIs, die das System bereitstellt
    • Data storage: Diskussion darüber, wie Daten gespeichert und verwaltet werden
    • Code and pseudo-code: Wird nur aufgenommen, wenn neue Algorithmen erklärt werden
    • Degree of constraint: Der Grad der Einschränkung des Lösungsraums ist einer der wichtigsten Faktoren, die die Form des Designdokuments beeinflussen
  • Alternatives considered: Listet alternative Designs auf, mit denen sich ein ähnliches Ergebnis vernünftigerweise erreichen ließe, und erläutert die Trade-offs jedes Designs sowie die Gründe für die Wahl des Hauptdesigns
  • Cross-cutting concerns: Erläutert, wie gemeinsame organisatorische Anliegen wie Sicherheit, Privatsphäre und Observability das Design beeinflussen

Wann man ein Design Doc schreiben sollte

• Ob ein Design Doc geschrieben werden sollte, hängt davon ab, ob die Vorteile wie organisatorischer Konsens über das Design, Dokumentation und Senior-Review größer sind als der zusätzliche Aufwand für das Schreiben des Dokuments
  • Wenn die Lösung eines Designproblems nicht aufgrund der Komplexität des Problems oder der Lösung mehrdeutig ist, ist der Wert des Dokuments gering
  • Ein Design Doc, das eher einem Implementierungshandbuch nahekommt, kann unnötig sein
  • Für Prototyping und schnelle Iteration kann der Overhead des Schreibens eines Design Docs ungeeignet sein

Der Lebenszyklus eines Design Docs

1. Creation and rapid iteration: Erstellung des Dokuments und schnelle Iteration mit Kolleginnen und Kollegen, um eine stabile Version zu erarbeiten
2. Review: Es wird mit einem breiteren Publikum geteilt und geprüft
3. Implementation and iteration: Wenn während der Implementierung Designänderungen auftreten, wird das Dokument aktualisiert
4. Maintenance and learning: Dient als am leichtesten zugänglicher Einstiegspunkt zum Verständnis des Systems

Meinung von GN⁺

• Ein Design Doc ist ein guter Weg, um bei den schwierigsten Problemen komplexer Softwareprojekte Klarheit zu gewinnen und Konsens herzustellen. Durch Vorabuntersuchungen lassen sich unnötige Coding-Arbeiten vermeiden und damit Kosten sparen, zugleich entstehen aber auch Kosten durch den Zeitaufwand für Erstellung und Review
• Deshalb sollte man klug entscheiden, ob für ein Projekt ein Design Doc erstellt werden sollte. Wenn Unsicherheit über das Softwaredesign besteht, eine frühe Einbindung erfahrener Ingenieurinnen und Ingenieure hilfreich ist, organisatorischer Konsens über das Design nötig ist, das Team gemeinsame Anliegen wie Sicherheit häufig übersieht oder High-Level-Dokumente zum Design von Legacy-Systemen benötigt werden, ist ein Design Doc eine Überlegung wert
• Es ist ein gutes Beispiel dafür, wie wichtig Dokumentation im Softwaredesignprozess ist, und dürfte besonders in großen Teams dabei helfen, eine konsistente Designkultur zu etablieren. Da Ingenieurinnen und Ingenieure Dokumentation wegen des Aufwands jedoch meiden könnten, scheint es wichtig, situationsgerechte Richtlinien für ein angemessenes Maß und einen passenden Umfang festzulegen
• Persönlich halte ich den Nutzen von Design Docs vor allem in drei Punkten für groß: 1) Berücksichtigung von Trade-offs je nach Komplexität des Designs, 2) frühes Erkennen von Designproblemen vor der Implementierung, 3) Bereitstellung einer Systemübersicht, damit neue Mitglieder sich schnell einarbeiten können. Man sollte jedoch darauf achten, dass das Dokument nicht übermäßig formalistisch wird oder sich zu weit von der tatsächlichen Implementierung entfernt
• Eine Möglichkeit wäre, Design Docs nur in frühen Projektphasen oder in Designphasen mit hoher Komplexität verpflichtend zu machen und zugleich Anreize zu schaffen, damit Ingenieurinnen und Ingenieure sie freiwillig verfassen. Es wäre auch sinnvoll zu betonen, dass das Schreiben solcher Dokumente zur Stärkung des technischen Portfolios einzelner Ingenieurinnen und Ingenieure beitragen kann

[GN⁺]

Hacker-News-Kommentare

Verschiedene Meinungen zur Kultur von Design-Dokumenten bei Google:

• Das Schreiben von Design-Dokumenten ist zu etwas für Beförderungen geworden, sodass sie tendenziell eher mit Blick auf Beförderungskomitees als auf die Menschen verfasst werden, die das System tatsächlich bauen.
• Arten von Design-Dokumenten:
  • Design-Dokumente für Beförderungen: Betonen eher, wie großartig das Projekt und das Unternehmen sind, als den eigentlichen Zweck des Projekts.
  • Turbo-Encapsulator-Design-Dokumente: Vollgestopft mit schwer verständlichem Fachjargon.
  • Design-Dokumente von Berufseinsteigern: Viel Umfang, aber wenig Inhalt.
  • Design-Dokumente voller unbelegter Behauptungen: Berufen sich auf Tatsachen, die „jeder kennt“, die in Wirklichkeit aber nicht verifiziert sind.
• Design ist Teil eines Softwareprojekts; deshalb ist es ein falscher Ansatz, vor dem Programmieren alles vollständig in Dokumenten zu planen.
• Vorab verfasste Dokumente liefern oft nur einen Anlass für kleinliche Kritik; wichtige Probleme lassen sich besser lösen, indem man frühzeitig mit den Beteiligten kommuniziert.
• Es ist nützlicher, Dokumente fortlaufend gemeinsam zu pflegen und zu aktualisieren.
• Die personellen Ressourcen, die für Design-Dokumente verschwendet werden, sind enorm.
• Die Kultur rund um Design-Dokumente bei Amazon war hervorragend, wirkte aber in anderen Unternehmen, die den Google-Stil übernommen haben, bedeutungslos.
• Es kam vor, dass ein Projekt ohne Genehmigung vorangetrieben wurde und erst im Nachhinein Feedback zum Design-Dokument kam.
• Design-Dokumente ersetzen mitunter die eigentliche Dokumentation, was paradoxerweise zu schlechterer Dokumentation führt.
• Design-Dokumente haben auch Vorteile: Sie helfen dabei, Gedanken zu ordnen, Mängel zu erkennen, die Kommunikation zu verbessern und den Arbeitsaufwand abzuschätzen.