Googles Kultur des Schreibens von Design Docs (2020)

 (industrialempathy.com)
4 Punkte von GN⁺ 2024-05-08 | 1 Kommentare | Auf WhatsApp teilen
  • Bei Google ist ein Design Doc ein Dokument, das vor dem Coden den Problemkontext, die High-Level-Implementierungsstrategie und zentrale Designentscheidungen festhält, um Risiken zu reduzieren, solange Designänderungen noch wenig kosten
  • Der Wert des Dokuments liegt weniger darin, fertigen Code zu erklären, sondern darin, Trade-offs und Alternativen sichtbar zu machen, damit die Organisation dieselben Entscheidungsgrundlagen teilt
  • Ein gutes Design Doc enthält je nach Projekt Kontext und Umfang, Ziele und Nicht-Ziele, das eigentliche Design, erwogene Alternativen sowie Querschnittsthemen wie Sicherheit, Datenschutz und Observability
  • Wenn das Design bereits klar ist oder das Dokument nur Implementierungsschritte auflistet, kann der Aufwand für Erstellung und Review eines Design Docs größer sein als der Nutzen
  • Das Dokument durchläuft Erstellung, Review, Aktualisierung während der Implementierung sowie Wartung und Lernen; wenn sich das Design vor dem Launch ändert, sollte auch das Dokument entsprechend aktualisiert werden

Die Rolle eines Design Docs

  • Bei Google ist ein Design Doc ein relativ informelles Dokument, das die Hauptautoren eines Softwaresystems oder einer Anwendung erstellen, bevor sie ein Coding-Projekt beginnen
  • Es enthält die High-Level-Implementierungsstrategie und zentrale Designentscheidungen; wichtiger als eine bloße Liste von Entscheidungen sind jedoch die Trade-offs, die zeigen, warum bestimmte Entscheidungen getroffen wurden
  • Ziel von Software Engineering ist nicht die Codeproduktion an sich, sondern das Lösen von Problemen; zu Beginn eines Projekts kann unstrukturierter Text daher knapper und verständlicher sein als Code
  • Ein Design Doc erfüllt im Entwicklungslebenszyklus mehrere Rollen
    • Es entdeckt Designprobleme früh, solange Änderungen noch wenig kosten
    • Es bildet innerhalb der Organisation Konsens über das Design
    • Es hilft, Querschnittsthemen wie Sicherheit, Datenschutz und Observability nicht zu übersehen
    • Es skaliert das Wissen von Senior Engineers in die Organisation hinein
    • Es bewahrt das organisatorische Gedächtnis zu Designentscheidungen
    • Es wird zu einem Artefakt, das das technische Portfolio der Designer zusammenfasst

Grundaufbau eines Design Docs

  • Für Design Docs gibt es keine strikte Vorlage; der erste Grundsatz ist, das für das konkrete Projekt am besten geeignete Format zu wählen
  • Häufig hilfreiche Bausteine sind jedoch Kontext und Umfang, Ziele und Nicht-Ziele, das eigentliche Design, erwogene Alternativen, Querschnittsthemen und eine angemessene Länge

  • Kontext und Umfang

    • Liefert einen groben Überblick über die Umgebung, in der das neue System stehen wird, und darüber, was tatsächlich gebaut werden soll
    • Es ist kein Anforderungsdokument und sollte daher knapp sein; der Fokus liegt darauf, Leser schnell auf den nötigen Hintergrund zu bringen
    • Ein gewisses Vorwissen kann vorausgesetzt werden, Details können verlinkt werden
    • Dieser Abschnitt sollte sich auf objektive Hintergrundfakten konzentrieren

  • Ziele und Nicht-Ziele

    • Fasst die Ziele des Systems und die mitunter noch wichtigeren Nicht-Ziele als kurze Bullet-Liste zusammen
    • Nicht-Ziele sind nicht einfach die Verneinung von Zielen wie „Das System darf nicht abstürzen“, sondern Punkte, die Ziele hätten sein können, aber ausdrücklich ausgeschlossen wurden
    • Beim Datenbankdesign ist ACID-Konformität ein gutes Beispiel für etwas, bei dem klar sein muss, ob es Ziel oder Nicht-Ziel ist
    • Auch wenn etwas ein Nicht-Ziel ist, kann man eine Lösung wählen, die diese Eigenschaft bietet, sofern sie keinen Trade-off verursacht, der die Zielerreichung behindert

Wie man das eigentliche Design schreibt

  • Der Abschnitt zum eigentlichen Design sollte mit einem Überblick beginnen und dann in Details hinabsteigen
  • Ein Design Doc ist der Ort, an dem die beim Softwaredesign entstandenen Trade-offs festgehalten werden
  • Auf Basis der Fakten des Kontexts sowie der Anforderungen in Form von Zielen und Nicht-Zielen sollte es eine Lösung vorschlagen und zeigen, warum eine bestimmte Lösung die Ziele am besten erfüllt
  • Der Vorteil des Dokumentformats liegt darin, dass die passende Darstellungsform für die jeweilige Problemmenge flexibel gewählt werden kann

  • System Context Diagram

    • In vielen Dokumenten kann ein system-context-diagram hilfreich sein
    • Dieses Diagramm zeigt das System als Teil einer größeren technischen Umgebung und hilft Lesern, das neue Design in einer Umgebung zu verstehen, die sie bereits kennen

  • API und Datenspeicherung

    • Wenn das zu entwerfende System eine API bereitstellt, ist es meist sinnvoll, die API zu skizzieren
    • Man sollte vermeiden, formale Interfaces oder Datendefinitionen einfach zu kopieren und einzufügen
    • Solche Definitionen werden leicht langatmig, enthalten unnötige Details und können schnell veralten
    • Der Fokus sollte auf den Teilen liegen, die für Design und Trade-offs relevant sind
    • Systeme, die Daten speichern, sollten behandeln, wie und in welcher groben Form die Daten gespeichert werden
    • Statt das gesamte Schema einzufügen, ist es besser, die für Designentscheidungen relevanten Teile zu erklären

  • Code und Pseudocode

    • In ein Design Doc sollte möglichst wenig Code aufgenommen werden
    • Außer zur Erklärung eines neuen Algorithmus sollte auch Pseudocode nur selten verwendet werden
    • Wenn es einen Prototyp gibt, der zeigt, dass das Design implementierbar ist, kann man angemessen darauf verlinken

Der Grad der Einschränkungen verändert die Form des Dokuments

  • Einer der wichtigsten Faktoren, die Softwaredesign und die Form eines Design Docs beeinflussen, ist der Grad der Einschränkungen im Lösungsraum
  • An einem Ende stehen Greenfield-Softwareprojekte, bei denen es nur Ziele gibt und jede Lösung möglich ist
    • Solche Dokumente können einen großen Umfang haben, müssen aber schnell Regeln definieren, um den Raum auf eine handhabbare Menge von Lösungen einzugrenzen
  • Am anderen Ende stehen Systeme, bei denen die möglichen Lösungen gut definiert sind, aber unklar ist, wie diese Lösungen kombiniert werden sollen, um das Ziel zu erreichen
    • Das kann ein Legacy-System sein, das schwer zu ändern ist
    • Es kann ein Library-Design sein, das innerhalb der Einschränkungen der Host-Programmiersprache funktionieren muss
  • In solchen Fällen lassen sich relativ leicht machbare Aufgaben auflisten, doch sie müssen kreativ kombiniert werden, um die Ziele zu erreichen
  • Wenn mehrere Lösungen allesamt unvollkommen sind, sollte sich das Dokument darauf konzentrieren, auf Basis der identifizierten Trade-offs den besten Ansatz zu wählen

Alternativen und Querschnittsthemen

  • Erwogene Alternativen

    • Dieser Abschnitt listet alternative Designs auf, mit denen ein ähnliches Ergebnis vernünftigerweise hätte erreicht werden können
    • Der Fokus sollte auf den Trade-offs liegen, die jedes Design erzeugt, und darauf, wie diese Trade-offs zur endgültigen Wahl geführt haben
    • Nicht gewählte Lösungen können knapp behandelt werden, dennoch ist dieser Abschnitt im Dokument sehr wichtig
    • Er sollte zeigen, warum andere Lösungen, die Leser erwarten könnten, im Hinblick auf die Projektziele weniger wünschenswert sind

  • Querschnittsthemen

    • Über diesen Abschnitt kann eine Organisation sicherstellen, dass Querschnittsthemen wie Sicherheit, Datenschutz und Observability immer berücksichtigt werden
    • Üblicherweise besteht er aus kurzen Abschnitten, die erklären, wie sich das jeweilige Thema auf das Design auswirkt und wie es behandelt wird
    • Teams sollten festlegen, welche Themen in ihrem Kontext als Standard gelten sollen
    • Google-Projekte verlangen aufgrund der Bedeutung ein eigenes Datenschutz-Design-Doc; außerdem gibt es dedizierte Reviews für Datenschutz und Sicherheit
    • Der Abschluss des Reviews ist bis zum Launch des Projekts erforderlich
    • Best Practice ist es, möglichst früh mit Datenschutz- und Sicherheitsteams zusammenzuarbeiten, damit das Design dies von Anfang an berücksichtigt
    • Wenn es zu dem Thema ein eigenes Dokument gibt, kann das zentrale Design Doc darauf verweisen, statt die Details zu wiederholen

Länge und Fälle, in denen man darauf verzichten kann

  • Angemessene Länge

    • Ein Design Doc sollte ausreichend detailliert sein, aber kurz genug, damit vielbeschäftigte Menschen es tatsächlich lesen können
    • Bei großen Projekten scheinen etwa 10 bis 20 Seiten ein sinnvoller Bereich zu sein
    • Wenn es deutlich länger wird, ist es möglicherweise besser, das Problem in handhabbare Teilprobleme aufzuteilen
    • Auch Mini-Design-Docs von 1 bis 3 Seiten sind möglich
    • Sie sind besonders nützlich für inkrementelle Verbesserungen oder Teilaufgaben in agilen Projekten
    • Sie durchlaufen dieselben Schritte wie ein langes Dokument, sind aber knapper und auf eine begrenztere Problemmenge fokussiert

  • Fälle, in denen man keines schreiben muss

    • Das Schreiben eines Design Docs verursacht Overhead
    • Ob man eines schreibt, hängt davon ab, ob die Vorteile durch Designkonsens, Dokumentation, Senior-Review usw. die Kosten der Dokumenterstellung übersteigen
    • Das zentrale Entscheidungskriterium ist, ob das Designproblem unklar ist
    • Die Unklarheit kann aus der Komplexität des Problems, der Komplexität der Lösung oder aus beidem entstehen
    • Wenn es keine Unklarheit gibt, ist der Wert des Dokumentationsprozesses gering
    • Wenn das Dokument im Grunde ein Implementierungshandbuch ist, ist ein Design Doc möglicherweise nicht nötig
    • Wenn es nur sagt „So werde ich es implementieren“, aber keine Trade-offs, Alternativen oder Entscheidungsbegründungen enthält, wäre es vielleicht besser gewesen, direkt das Programm zu schreiben
    • Wenn die Lösung so offensichtlich ist, dass es keine Trade-offs gibt, ist der Wert des Dokuments niedrig
    • Der Aufwand für Erstellung und Review eines Design Docs kann zu Prototyping und schneller Iteration nicht passen
    • Ein agiles Vorgehen bedeutet nicht, dass man nicht gründlich über Lösungen für bekannte Probleme nachdenken muss
    • Prototyping selbst kann Teil der Erstellung eines Design Docs sein; „wir haben es ausprobiert und es funktioniert“ kann ein starkes Argument für eine Designentscheidung sein

Der Lebenszyklus eines Design Docs

  • Der Lebenszyklus eines Design Docs besteht aus vier Phasen
    1. Erstellung und schnelle Iteration
    2. Review
    3. Implementierung und Iteration
    4. Wartung und Lernen

  • Erstellung und schnelle Iteration

    • Das Dokument wird vom Autor allein oder gemeinsam mit Co-Autoren geschrieben
    • Anschließend wird es mit Kollegen geteilt, die den Problemraum am besten kennen, und schnell iteriert
    • Klärende Fragen und Vorschläge der Kollegen führen das Dokument zu einer relativ stabilen ersten Version
    • Bei Google gibt es Engineers und Teams, die Dokumente lieber mit Versionsverwaltung und Code-Review-Tools erstellen, aber die meisten Design Docs werden in Google Docs geschrieben und nutzen dessen Kollaborationsfunktionen intensiv

  • Review

    • In der Review-Phase wird das Dokument einem breiteren Publikum zugänglich gemacht als nur den ursprünglichen Autoren und engen Mitwirkenden
    • Reviews können großen Mehrwert schaffen, aber auch zur Overhead-Falle werden und sollten daher sorgfältig gehandhabt werden
    • Ein leichter Ansatz besteht darin, das Dokument an eine breitere Team-Mailingliste zu schicken, damit Personen die Gelegenheit haben, es sich anzusehen
    • Die Diskussion findet hauptsächlich in Kommentar-Threads des Dokuments statt
    • Ein schwergewichtiges Verfahren ist ein formelles Design-Review-Meeting, in dem der Autor das Dokument vor einem Publikum aus Senior Engineers präsentiert
    • Viele Teams bei Google haben regelmäßige Meetings für solche Reviews
    • Auf solche Meetings zu warten, kann den Entwicklungsprozess erheblich verlangsamen
    • Das lässt sich abmildern, indem man das wichtigste Feedback direkt einholt und ein breiteres Review nicht zum Blocker für den Fortschritt macht
    • Als Google noch ein kleineres Unternehmen war, war es üblich, Designs an eine zentrale Mailingliste zu schicken, wo Senior Engineers sie bei Gelegenheit reviewten
    • Dieser Ansatz hatte den Vorteil, unternehmensweit eine relativ einheitliche Kultur des Softwaredesigns zu schaffen
    • Mit dem starken Wachstum der Engineering-Organisation wurde es schwierig, den zentralisierten Ansatz beizubehalten
    • Der Hauptwert eines Reviews liegt darin, die gebündelte Erfahrung der Organisation in das Design einfließen zu lassen
    • Insbesondere hilft die Review-Phase zuverlässig dabei, dass das Design Querschnittsthemen wie Observability, Sicherheit und Datenschutz berücksichtigt
    • Der Kernwert eines Reviews liegt weniger darin, Probleme überhaupt zu entdecken, sondern darin, sie früh im Entwicklungslebenszyklus zu finden, solange Änderungen noch wenig kosten

  • Implementierung und Iteration

    • Wenn ausreichend sicher ist, dass weitere Reviews keine großen Designänderungen mehr verlangen werden, ist es Zeit, mit der Implementierung zu beginnen
    • Wenn der Plan auf die Realität trifft, können Defekte, unbehandelte Anforderungen und Annahmen auftreten, die sich als falsch erweisen, sodass Designänderungen nötig werden
    • In diesem Fall wird dringend empfohlen, das Design Doc zu aktualisieren
    • Als Faustregel gilt: Wenn das entworfene System noch nicht gelauncht ist, sollte das Dokument unbedingt aktualisiert werden
    • In der Praxis gelingt es Menschen oft nicht, Dokumente gut aktuell zu halten, und aus anderen praktischen Gründen werden Änderungen häufig in neue Dokumente ausgelagert
    • Das Ergebnis kann dann eher einer US-Verfassung mit angehängten Amendments ähneln als einem einzigen konsistenten Dokument
    • Wenn das ursprüngliche Dokument auf solche Änderungsdokumente verlinkt, hilft das späteren Wartungsprogrammierern sehr dabei, das Zielsystem durch Design-Doc-Archäologie zu verstehen

  • Wartung und Lernen

    • Wenn Google-Engineers mit einem System in Berührung kommen, das sie zum ersten Mal anfassen, lautet eine häufige erste Frage: „Wo ist das Design Doc?“
    • Wie andere Dokumente neigen auch Design Docs dazu, mit der Zeit von der Realität abzuweichen, sind aber oft der zugänglichste Einstiegspunkt, um den Denkprozess zu verstehen, der hinter dem System stand
    • Autoren sollten ihr eigenes Design Doc nach ein bis zwei Jahren noch einmal lesen
    • Prüfen, was sie richtig eingeschätzt haben
    • Prüfen, was sie falsch eingeschätzt haben
    • Überlegen, was sie heute anders entscheiden würden
    • Der Prozess, diese Fragen zu beantworten, hilft dabei, als Engineer zu wachsen und die eigenen Fähigkeiten im Softwaredesign im Laufe der Zeit zu verbessern

Entscheiden, wann man mit einem Design Doc beginnen sollte

  • Ein Design Doc ist eine gute Möglichkeit, bei der Lösung schwieriger Probleme in Softwareprojekten Klarheit zu gewinnen und Konsens herzustellen
  • Es kann Kosten sparen, indem es Sackgassen beim Coden reduziert, die durch Vorab-Recherche vermeidbar gewesen wären
  • Gleichzeitig entstehen Kosten, weil Erstellung und Review Zeit benötigen
  • Man kann die folgenden Fragen berücksichtigen
    • Ist das richtige Softwaredesign unsicher, und ist es sinnvoll, im Voraus Zeit zu investieren, um Sicherheit zu gewinnen?
    • Ist es hilfreich, Senior Engineers bereits in der Designphase einzubeziehen, die möglicherweise nicht jede Codeänderung reviewen können?
    • Ist das Softwaredesign unklar oder umstritten, sodass organisatorischer Konsens wertvoll ist?
    • Vergisst das Team manchmal Datenschutz, Sicherheit, Logging oder andere Querschnittsthemen im Design?
    • Gibt es einen starken Bedarf an Dokumenten, die High-Level-Einblicke in das Design von Legacy-Systemen innerhalb der Organisation bieten?
  • Wenn die Antwort auf drei oder mehr dieser Fragen „ja“ lautet, ist ein Design Doc wahrscheinlich ein guter Weg, das nächste Softwareprojekt zu beginnen

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2024-05-08
Hacker-News-Kommentare

  • Ich habe das Unternehmen wegen der Kultur rund um Design-Dokumente bei Google verlassen.
    Kurz nach meinem Einstieg schrieb ich ein sehr ausgearbeitetes Dokument für eine relativ kleine Aufgabe, die ich in anderen Produktbereichen schon mehrfach gemacht hatte, und ein Kollege nahm mich beiseite und sagte: „So macht man das hier nicht.“
    Mein Vorschlag war nur eine kleine Abwandlung des empfohlenen Ansatzes, aber man sagte mir, ich solle „mehr Wege bewerten, wie man das lösen kann“. Auf meine Frage nach dem Grund bekam ich die Antwort: „Damit man sieht, dass du es breit abgewogen hast.“
    Bei Google gibt es eindeutig Fake-Arbeit, und ich wünschte, ich wäre in einem anderen Team gelandet.

    • Belohntes Verhalten wird zum tatsächlichen Verhalten. Früher waren Design-Dokumente ein Werkzeug, um sich auf eine Richtung zu einigen und Kollegen Kontext zu geben, aber als die Zahl der Mitarbeiter später exponentiell wuchs, forderten wohlmeinende Manager Dokumente für Leistungsbeurteilungen ein, und ab da geriet alles aus dem Ruder.
      Die Google-Kultur ist zu einer Art Cargo-Kult geworden, der sich selbst nachahmt.
      Einige Firmen, bei denen ich nach Google war, wollten nur ungern im Detail über ihre Beförderungsprozesse sprechen, weil sie gesehen hatten, was passiert, wenn Leute darauf hin feinoptimieren.
    • Wahrscheinlich liegt das an der Kultur von Teams, die alte und ausgereifte Produkte betreuen. Dort arbeitet man selbst für den Launch kleiner Projekte mit mindestens 10 Personen zusammen, in meinem Fall meist mit 20 bis 30, und der Wirkungskreis reicht bis zu 100 bis 500 Personen.
      Alle sind beschäftigt, daher kann man nicht mit jedem locker ein 1:1 führen, und wenn man kein ordentliches Stakeholder-Review bekommt, ist die Wahrscheinlichkeit groß, dass später verärgerte Leute auftauchen und den Rollback des Launches erzwingen.
      In diesem Kontext ist ein Design-Dokument ein asynchrones Kommunikationsmittel für informationsdichte Themen. Wenn ein Produkt erfolgreich ist, führt man über dieses Dokument auch noch mit Menschen Gespräche, die erst 10 Jahre später dazukommen.
      Mehr als einmal haben mich zufällige Design-Dokumente aus dem Jahr 2010 gerettet, weil sie seltsame Entscheidungen erklärt haben, die uns bis heute behindern. Für kleine, bewegliche Teams oder weniger komplexe Arbeiten passt das vielleicht nicht gut, aber selbst wenn es in der Engineering-Kultur zu Cargo-Kult geworden ist, gibt es dafür meist doch einen Grund und Kontext.
    • Wenn es praktisch nur eine Seite Dokumentation braucht, weil es faktisch nur einen einfachen und klaren Weg gibt, würde ich trotzdem in diesem Punkt Google verteidigen.
      Wenn man etwas entwirft und es nur eine einzige betrachtete Lösung gibt, dann gibt es entweder kein Design oder es wurde nicht gründlich genug durchdacht. Optionen und Trade-offs sind das, was Design ausmacht.
    • Bei uns gibt es das entgegengesetzte Problem. Wenn man für eine relativ kleine Aufgabe um ein sehr hochwertiges Design-Dokument bittet, heißt es: „Es gibt mehrere Wege, das zu machen, daher sind solche Dokumente nutzlos, und die Aufgabe ist klein genug, dass ein Engineer einfach einen davon auswählen und umsetzen kann.“
      Viele dieser Leute sind externe Berater, die seit mehr als 15 Jahren mit der Firma arbeiten, daher gibt es schon gewisse Standards, einfach weil immer dieselben Leute immer dieselben Aufgaben gemacht haben. Trotzdem bemühen sie sich, ein Strohmann-Argument aufzubauen à la „Was ist, wenn die Leute den Standards nicht folgen?“
      Am Ende gibt es entweder keine Design-Dokumente oder völlig veraltete, und das Unternehmen beschäftigt Jahr für Jahr dieselben Berater weiter zu aufgeblähten Kosten.
    • In anderen Teams hatte ich auch dieses Gefühl. Es wirkte so, als würde erwartet, dass man Dokumente um der Dokumente willen schreibt, also eher wie Cargo-Kult-Engineering.
      Jetzt bin ich in einem Team mit vielen langjährigen Googlern mit über 15 Jahren Betriebszugehörigkeit, und dort gibt es Design-Dokumente nur, wenn sie wirklich nötig sind, etwa wenn mehrere Systeme betroffen sind oder es offensichtlich komplex ist und viele Trade-offs gibt. Ansonsten heißt es einfach: „Schreib ein CLS.“

  • Bei Google scheinen Design-Dokumente ein zentrales Element der Beförderungsunterlagen zu sein, und daraus ergeben sich wohl Probleme
    Deshalb werden Dokumente eher mit Blick auf das Beförderungsgremium geschrieben als für die eigentlichen Leute, die an dem System arbeiten

    • So war es in jedem Unternehmen, in dem ich bisher war. Die Karriere hängt stärker von Sichtbarkeit ab als von Ruf oder Können. Design-Dokumente sind für Vorgesetzte sehr gut sichtbar
      Jedes Mal, wenn ich in ein neues Unternehmen komme, schlage ich vor, Design-Dokumente einzuführen, und das macht sofort einen guten Eindruck bei der Führungsebene :)
    • Dadurch folgen viele Dokumente unnötig komplexeren Design-Formaten, obwohl das gar nicht nötig wäre. Ziel ist es, bei Leuten, die nur Zeit haben, das Dokument zu überfliegen, mehr Leistungspunkte zu bekommen
      Viele Dokumente, die ich gelesen habe, wirkten so, als sei die gewünschte Entscheidung schon vorher festgestanden und als hätte man zu Beginn des Dokuments zwei oder mehr erfundene Alternativen hinzugefügt, nur um genau diese Entscheidung gut aussehen zu lassen. Eine ist dann zu simpel, eine andere unnötig überengineert, und am Ende wird die vernünftig wirkende Option gewählt
    • Entwickler sagen ganz offen, dass sie Design-Dokumente für das Beförderungsgremium schreiben. Das ist das Ziel, alles andere ist zweitrangig
      Weil man nicht weiß, welches Design-Dokument später in den Beförderungsunterlagen landet, wird selbst die kleinste Arbeit als Design-Dokument festgehalten. Es gibt zwar das Konzept eines einseitigen Design-Dokuments, aber meistens wächst es von einer Seite auf mehrere an
      Selbst für ein einwöchiges Projekt wird ein Design-Dokument geschrieben, und ich musste schon 20-, 30- oder 40-seitige Design-Dokumente prüfen, die in anderen Unternehmen nur ein einziges JIRA-Ticket gewesen wären
      Viele haben gelernt, dass das Beförderungsgremium ein „Dokument, das der Autor allein geschrieben hat“ sehen will. Ob das stimmt oder nicht, dieser Glaube macht alles langsamer und hemmt den Wissensaustausch. Ich habe sogar Software Engineers gesehen, die über ein Quartal lang isoliert waren und nur Design-Dokumente geschrieben haben
      In einem Design-Dokument sollte das eigentliche Design zentral sein, aber die übrigen 99 % sind Problemdefinition. Zu oft habe ich in Reviews die Problemdefinition verbessert, nur damit das Design verworfen werden musste und der Großteil des Dokuments neu geschrieben werden musste
      Am schlimmsten ist es, wenn eine verbesserte Problemdefinition offenlegt, dass eine einfache Lösung reicht und das komplexe Design gar nicht nötig ist. Der Autor hat viel Zeit in das komplexe Design investiert, und historisch haben viele Gremien genau diese Komplexität als Grundlage für Beförderung gewertet, daher gibt es Widerstand gegen die einfache Lösung
      Ich habe auch Design-Dokumente ohne jegliche Alternativen gesehen. Darin stand einfach nur in arbeitsintensiver Form, was getan werden soll oder was jemand tun möchte
      So werden Design-Dokumente aus der Ferne fast zu einer Art Bug-Tracking-System. Alle arbeiten an ihren eigenen Design-Dokumenten, aber nicht an Bugs. Mit Bugs kann man schließlich nicht befördert werden
      Es heißt oft, in einem neuen Team müsse man sich nur die Design-Dokumente ansehen, aber in der Praxis werden sie häufig nicht zentral nachverfolgt. In vielen Teams gehören Design-Dokumente nicht dem Team oder dem Projekt, sondern einzelnen Personen, weil sich so garantieren lässt, dass niemand anderes beigetragen hat, und auch das liegt wieder am Beförderungsgremium
      Es gibt auch viele Design-Dokumente, auf die man keinen Zugriff hat, nicht weil sie streng geheim wären, sondern einfach weil es so ist. Ein Team hat nicht nur zwei oder drei Design-Dokumente, sondern einen ganzen Berg, den man lesen müsste. Bei Googles interner Wechselhäufigkeit von etwa zwei Jahren verschwinden viele Dokumente mit der Zeit
      In einem anderen Unternehmen wäre das ungefähr so, als würde man einem Neuzugang sagen: „Alles, was du wissen musst, ist, alle geschlossenen Bugs oder alle Commit-Messages im Main-Branch zu lesen.“
      Anderswo wäre man nach dem Mittagessen vermutlich abgefangen worden und hätte mit dem Team mehrere Stunden vor einem Whiteboard gestanden, um das Problem zu definieren. Seniors hätten Juniors dabei in Echtzeit gezeigt, wie man über solche Probleme nachdenken sollte, und man hätte schnell iteriert
      Das meiste hätte man ins Bug-Tracking-System geschrieben oder, wenn es etwas Größeres gewesen wäre, in ein Projekt-Wiki oder einen Ordner, sodass es allen gehört hätte
      Alle oben genannten Probleme lassen sich beheben, und ich habe tatsächlich versucht, sie zu verbessern, aber Kultur ändert sich langsam. Das Konzept von Design-Dokumenten an sich ist gut, aber es hat Fallstricke, und die Art, wie viele Menschen bei Google sie verwenden, ist nicht die Antwort
    • Außerdem dient es auch dazu, bürokratische Anforderungen zu erfüllen. Man zeigt Leadership, indem man Kommentare zu den Dokumenten anderer hinterlässt
      Ich vermisse Design-Dokumente, deren Wert höher ist als ihre Kosten
    • Ich bin mir nicht sicher, worin genau der Unterschied besteht. Vielleicht geht es nur darum, mehr Kontext zu liefern, als das Team tatsächlich braucht, oder das Problem komplexer wirken zu lassen, als es ist
      Im Großen und Ganzen habe ich aber nicht gesehen, dass diese Strategie wirklich funktioniert
      Andererseits gab es lange Dokumente zur Kontextvermittlung, in denen zusammengefasst wurde, was das Team getan hat, was es gerade tut und worin die Probleme bestehen, und solche Dokumente neigten dazu, lang und aufgebläht zu werden

  • Ich arbeite zwar bei dem erwähnten Unternehmen, habe aber nicht dieselbe Erfahrung wie der Autor.
    Es gibt verschiedene Arten von Design-Dokumenten, und ich fand keines davon besonders nützlich. Bei Google habe ich nur selten wirklich nützliche Design-Dokumente gesehen. Design-Dokumente wirken auf mich wie etwas für Ingenieure mit übermäßig prozessorientierter Arbeitsweise.
    Die Arten, die ich gesehen habe, sahen ungefähr so aus: Design-Dokumente für die Beförderung erklären nicht, welches Problem gelöst werden soll, sondern nur, wie großartig dieses Projekt ist und wie sehr es das Unternehmen verbessert. Die logische Schlussfolgerung ist, dass der Verfasser befördert werden sollte.
    Das Turbo-Encabulator-Design-Dokument ist ein Dokument voller technischer Worthülsen mit Begriffen, die man noch nie gehört hat, sodass es niemand außer den Senior-Leuten im Team verstehen kann. Manchmal bin ich mir nicht einmal sicher, ob die Seniors es verstehen.
    Das Design-Dokument von frischen Hochschulabsolventen enthält keinen Inhalt, ist aber so lang wie möglich, weil jemand, der gerade von der Uni kommt, irgendetwas beweisen will. Es vermittelt keine Informationen und wird oft auf etwa 70 Seiten aufgebläht, indem bereits geschriebener Code großflächig per Copy-and-paste eingefügt wird.
    Das Design-Dokument mit erfundenen Fakten ist voller Formulierungen wie „das weiß doch jeder“ oder „alle sagen das“. Nicht so unverblümt wie ein Politiker, aber es drückt das eigene Design mit Aussagen durch wie „das folgt Best Practices“ oder „diese Software ist langsam, daher …“. Es fehlt, wer diese Best Practices definiert hat, warum sie gut sein sollen, was genau langsam ist, ob es gemessen wurde oder ob es nur ein Eindruck der Endnutzer ist.
    99 % der Design-Dokumente, die ich gesehen habe, waren so. Es gibt Ausnahmen, aber meiner Erfahrung nach sind sie sehr selten. Es überrascht mich, dass der Autor diese Praxis so stark propagiert. Andererseits war er kein Ingenieur, sondern Director, also ergibt ein Design-Dokument aus dieser Position vielleicht eher Sinn, auch wenn ich immer noch nicht weiß, welchen Wert solche Leute eigentlich liefern.
    [1] https://en.wikipedia.org/wiki/Turbo_encabulator

    • Das scheint sich geändert zu haben. Ich habe dort von 2006 bis 2014 gearbeitet, und damals waren die meisten Design-Dokumente nützlich und folgten der im Artikel beschriebenen Grundstruktur. Es gab nur keine Systemkontextdiagramme.
      Was mir früh auffiel, war, dass Design-Dokumente, die in Google Docs gepflegt wurden, tendenziell von geringerer Qualität waren als solche im Versionsverwaltungs-Repository. Ich weiß nicht, ob das ein Ersatzindikator für den Zeitpunkt der Erstellung war oder ob der Code-Review-Prozess einfach strenger war als das Bearbeiten in Docs.
      Als ich einmal ein großes Design-Dokument schrieb, vielleicht etwa 40 Seiten, habe ich es dem damaligen Brauch entsprechend in handgeschriebenem HTML verfasst und durch das Code-Review-System laufen lassen. Ich habe es auch in die zentrale Mailingliste und auf den Webserver gestellt, und es war gut, Feedback von Mitarbeiter Nr. 3 zu bekommen. Da alles zentral und nach Kategorien sortiert lag, war es leicht zu finden.
      Ich kann mich nicht erinnern, dass ein einzelnes Design-Dokument damals so wichtig gewesen wäre, dass es für eine Beförderung stark ins Gewicht gefallen wäre. Bei Beförderungen sollte es um den Gesamteinfluss gehen, nicht um ein bestimmtes Artefakt. Natürlich hatte das System große Mängel, und es gab oft erstaunliche Entscheidungen im negativen Sinn, aber ich erinnere mich nicht daran, damals Design-Dokumente gelesen zu haben, die auf Leistungsbeurteilungen optimiert waren.
      Wenn du die Website mit den frühen handgeschriebenen HTML-Design-Dokumenten findest, würde ich empfehlen, sie durchzusehen. Vielleicht hätten sie sich noch nützlicher angefühlt, als das damalige System noch aktiv im Einsatz war.
      Einige ältere Dokumente wie SmartASS waren voller ausführlicher Erklärungen zu den zugrunde liegenden Gleichungen und Modellen, was sehr geholfen hat zu verstehen, wie etwas funktioniert und warum dieser Ansatz gewählt wurde. Das hat später auch meine eigene Design-Arbeit beeinflusst. Ich war kein Director, sondern einfach Ingenieur, und für mich war das tatsächlich hilfreich.
      Auch unter den mit der chromium.org-Website verknüpften Chrome-Design-Dokumenten gab es früher einige, die beim Verständnis der Architektur geholfen haben.
    • Ich habe gesehen, dass Design-Dokumente gut funktionieren, wenn es im Verhältnis zu Seniors relativ viele Junior-Rollen gibt.
      Sie zwingen Junior-Entwickler dazu, die Lösung im Voraus durchzudenken und ihre Entscheidungen zu begründen, und ermöglichen Senior-Entwicklern, diese Entscheidungen zu prüfen und asynchrones Feedback zu geben.
      Allerdings habe ich immer nur in Startups gearbeitet und nie in einer Engineering-Organisation mit mehr als 30 bis 40 Leuten. Big Tech mag anders sein, aber meine Erfahrung war positiv.
    • Es scheint noch eine Kategorie zu fehlen: das Bitte lasst mich endlich mit dem Coden anfangen-Dokument.
    • Ich finde, der Zweck technischer Dokumentation, egal ob Design-Dokument oder kürzeres Dokument, ist einfach. Sobald man an den Punkt kommt, an dem man nicht mehr alle Details eines Projekts gleichzeitig im Kopf behalten kann, sollte man es aufschreiben.
      Genauso sollte man ein Dokument schreiben, wenn die Erklärung für andere Ingenieure zu lange dauert, selbst wenn es nur etwa 30 Minuten sind, um Zeit zu sparen.
      Ich verstehe nicht, wie man überhaupt denken kann, man müsse gar nichts dokumentieren.
    • Bei der zweiten Art war es für mich eher im Sinne von „Ich muss dem Team oder dem technischen Leiter vermitteln, was ich tue und wie ich dieses Problem löse“.
      Später, wenn es an die Vorbereitung auf eine Beförderung ging, wurde dann genügend Kontext zu Dokumenten aus Kategorie 2 hinzugefügt, sodass daraus Kategorie 1 wurde.

  • Dokumentation ist grundsätzlich gut, aber dieser Ansatz wirkt fehlerhaft.
    Es heißt, dass der Hauptautor eines Softwaresystems oder einer Anwendung „bevor mit dem Coding-Projekt begonnen wird“ ein relativ informelles Dokument erstellt, aber das Design selbst ist das Coding-Projekt, beides ist dieselbe Arbeit.
    Die Vorstellung, man könne das Design vollständig auf Papier ausarbeiten, bevor man Code committet, ist falsch. Auch der Ansatz mit Design-Dokumenten erkennt in Wirklichkeit an, dass man früh etwas Code schreiben muss, versucht das aber streng als „Prototyp zum Nachweis der Umsetzbarkeit des Designs“ abzugrenzen.
    Die große Eigenschaft eines vorgelagerten Design-Dokuments ist, dass es Menschen erlaubt, vor dem eigentlichen Coding kleinlich zu werden, also Reviews zu machen. Meiner Erfahrung nach führt das dazu, dass das Dokument immer weiter anwächst, mit mehr Andeutungen und bedeutungslosen Diskussionen über Alternativen, und eher zu einem „Bitte lasst mich das jetzt endlich bauen“-Dokument wird als zu einem Design-Dokument.
    Wenn es ein wichtiges Architekturproblem gibt, das einen Kurswechsel erfordert, ist es besser, im Vorfeld mit den richtigen Leuten zu sprechen und zusammenzuarbeiten, statt ein detailliertes Design-Dokument zu erstellen und dann abgeschossen zu werden.
    Wenn man näher bei der Idee eines „relativ informellen Dokuments“ bleibt und das Dokument während des Fortschritts aktualisiert, kann es tatsächlich nützlich sein. So kann man ein funktionierendes System und hilfreiche Dokumentation gleichzeitig erstellen. Dann ist es allerdings weniger ein Design-Dokument als vielmehr Dokumentation als Teil eines fortlaufenden und kollaborativen Prozesses.

    • Wenn ein Projekt groß genug und gut genug durchdacht ist, kann man Architekturänderungen ohne große Zusatzkosten im Verhältnis zum Gesamtaufwand einarbeiten.

  • Ich bin Googler. Ich habe auch mehrere Papers veröffentlicht, aber früher habe ich es gehasst, Designdokumente zu schreiben. Seit ein paar Jahren ist mir ihr Hauptnutzen für mich selbst klar geworden
    Sie helfen mir, die unmittelbaren Teile einer Idee aus dem Kopf zu bekommen, sodass ich zu tieferen Aspekten und produktiveren Überlegungen übergehen kann
    Mängel werden sichtbarer, besonders für mich selbst
    Es wird leichter, Gedanken zu teilen, besonders mit Leuten in anderen Büros. Sie geben meist sehr gutes Feedback
    Sie helfen mir, den nötigen Arbeitsaufwand viel besser einzuschätzen, als wenn ich einfach anfange zu coden
    Oft zeigen sie auf, was ich vor dem Coden noch lernen muss, welche angrenzenden Systeme betroffen sind oder welche technischen Entscheidungen sinnvoll wären
    Für Beförderungen sind sie auch gut, aber erfolgreiche Projekte sind besser. Ich höre oft, dass meine Dokumente nützlich sind, also scheint es, als hätte ich da etwas richtig gemacht

    • Geht mir genauso. Der größte Nutznießer von Designdokumenten war mein Denkprozess. Ich bin ehemaliger Googler

  • Funktioniert das tatsächlich? Ist es besser als die Alternativen? Wo findet diese Diskussion statt?
    Als ich bei Amazon gearbeitet habe, war die Kultur rund um Designdokumente großartig. Mein nächster Job schien die Engineering-Kultur von Google oder die allgemeine Startup-Kultur aus SF übernommen zu haben, aber der Prozess für Designdokumente wirkte wie ein nutzloser Witz

    • Designdokumente sind ein Mittel zur Diskussion. Die Idee ist, dass sie der effizienteste Weg sind, Absicht, Motivation und die Gründe zu vermitteln, warum man andere Alternativen nicht gewählt hat
      Sie sind ein Baustein, der in eine breitere Arbeitskultur eingebettet ist. Wenn man allein arbeitet, ist es eine luxuriöse Übung; in einem großen Team nutzt man damit mehr Expertise des gesamten Teams und hat zugleich Dokumentation
      Es gibt einige Fehlformen. Ein klassisches Missverhältnis ist, Output über Ergebnis zu stellen. Dann schreibt man ein 40-seitiges Dokument für die Beförderung, was außer in sehr juniorigen Fällen, in denen man eher zeigt, dass man Sätze aneinanderreihen kann als tiefes Engineering zu leisten, meist nicht gut funktioniert
      Für Teams, die allein arbeiten, ist es auch zu viel. Andere kleine Teams können sich auch allein über Issues, etwa in Jira, und separate Sessions zum Abgleich von Ideen ausreichend verständigen
      Auch Engineers müssen darin eingearbeitet werden, wie man effektive Designdokumente schreibt. Der obere Kommentar, in dem jemand frustriert war, weil der erste Versuch nicht sofort bejubelt wurde, könnte ein Signal dafür sein
      Über Code zu schreiben ist schwer, und auf HN wird solche Übung gewöhnlich gelobt. Wenn man im Team arbeitet, sollte man vorsichtig werden, wenn es sich so anfühlt, als sei die eigene Arbeit nur dann wertvoll, wenn sie sich jederzeit in einem teilbaren Dokument erklären lässt und kein tieferes Nachdenken erfordert
    • Mich würde interessieren, was an der Amazon-Kultur für Designdokumente am besten war

  • Wenn ein großer Investor unter falscher Identität ein paar Wochen lang als Google-Engineer arbeiten würde, wäre er sofort ein aktivistischer Investor, der Sundars Entlassung fordert
    Das Ausmaß an verschwendetem menschlichem Potenzial durch Googles Kultur der Designdokumente ist kaum zu begreifen

    • Ich glaube, die Leute überschätzen den Aufwand, der in die meisten Designdokumente fließt, enorm
      Die meiste Entwicklung läuft einfach, und gelegentlich schreibt man hastig ein Dokument, um einen CL leichter rechtfertigen zu können
      In vielleicht einem von zehn Fällen sieht man, dass es jemand deutlich übertreibt, aber für den durchschnittlichen Software Engineer ist das kein großer Zeitverlust
    • Carl Icahn wäre genau der Richtige dafür. https://www.bloomberglinea.com/english/i-fired-12-floors-of-...
    • Meine Hypothese ist, dass das spätere Google darauf ausgelegt ist, Monopolgewinne zu kaschieren
      Wenn man so viel Geld wie möglich verbrennen wollte, würde man ein Unternehmen wohl genau so aufbauen

  • Eine Kultur der Designdokumente drängt alle in eine Rechtfertigungsschicht für ihre eigene Arbeit. Eine Rechtfertigungskultur ist für Innovatoren ein ziemlich unterdrückendes Muster, selbst wenn Kollegen sie kulturell verstärken
    Dieses System neigt dazu, visionäre Versuche und ambitionierte Projekte zu verhindern. Nicht konsensorientierte Bemühungen werden unterdrückt, und wenn man außerhalb der „erlaubten Normen“ denkt, wird man von der Gruppe bestraft
    Solche Systeme erzeugen Gruppendenken, und der traditionszentrierte Charakter von „so arbeiten wir hier“ erzwingt im Kern eine Situation, in der andere Arbeitsweisen zum Karriererisiko werden
    Im Silicon Valley gibt es in allen möglichen Formen Unternehmenskulturen, die sich auf Floskeln stützen, verpackt in Begriffe wie „Agile“ und „Design Thinking“; meistens ist das eher eine Institutionalisierung, die sich als der „richtige Weg“ ausgibt, begleitet von zusätzlichen Mechanismen, die die Variante von Engineering-Kultkultur sozial erzwingen, zu der dieser Campus gelangt ist
    Ich habe unzählige Leute getroffen, die Google verlassen haben, obwohl es dort sehr bequem war, weil es ihre Karriere einschränkte, und das waren nicht wenige

    • Deshalb bezahlt Google so gut. Es ist eine Falle. Und es gab auch den äußerlichen Status, dort zu arbeiten, aber der ist inzwischen weitgehend verblasst
      Das bringt die Frustration, die ich dort erlebt habe, exakt auf den Punkt. Das Gehalt hätte ich allerdings trotzdem gern wieder
      Was Agile angeht: Ich habe Agile vor etwa 20 Jahren in Form von eXtreme Programming kennengelernt, und das war völlig anders als das Cargo-Cult-artige SCRUM oder seine Nachahmungen von heute
      Es war letztlich ein Bündel von Prinzipien, das Entwicklern kreative Gestaltungsmacht gab, Manager davon abhielt, sich in die Methode einzumischen, und es ihnen ermöglichte, Dinge umzusetzen. Stattdessen gab es dem Kunden das Recht zu sagen, was wann und in welchem Umfang getan werden soll
      Entwickler schätzen selbst, und „man baut nicht, was man nicht braucht“ ist das Prinzip. Es gibt kein großes Upfront-Design, und Refactoring, Tests, Architektur und Design sind keine separaten Stories oder Aufgaben, sondern als Standard-Best-Practices Teil des fortlaufenden Overheads
      Planungsmeetings bestehen daraus, dass Kollegen sich im Raum abstimmen, und Stories werden als Post-its auf dem Whiteboard in minimalen nichttechnischen Begriffen formuliert. Stand-ups bedeuten tatsächlich, dass die Leute im Kreis stehen und sehr kurze Updates geben, gerade so viel, wie für andere interessant sein könnte, und nicht ein Ritual, um zu beweisen, dass man heute zur Arbeit erschienen ist, oder um sich zu produzieren
      In diesem System ist Design eine Eigenschaft, die daraus entsteht, dass ein kreatives Kollektiv von Experten zusammenarbeitet. Es schließt Designdokumente nicht aus und umfasst weiterhin Architekturdiskussionen, verlangt aber keinen expliziten PRD-/Designdokument-Prozess
      Ich würde gern wieder an so einem Ort arbeiten. Google war das genaue Gegenteil, und alles dauerte viel zu lange
    • Deshalb bringt Google überhaupt keine Produkte zustande. Mein neues Pixel 7 ist gestern kaputtgegangen
      Dieses falsche Auftreten nach dem Motto „wir sind sehr schlau“ ist auch eine Form von Beschäftigungstherapie. Ein Unternehmen sollte sich auf Produkte konzentrieren, die tatsächlich funktionieren, und sich daran messen

  • Ebenfalls ein weiterer Googler
    Es gibt bereits viele gute Kommentare dazu, dass Googles Designdokumente nutzlos sind, aber ich möchte noch eine weitere Perspektive hinzufügen, warum ich sie problematisch finde.
    Designdokumente sind, wie erwähnt, Material für Beförderungen und erzeugen deshalb enorm viel Ballast. Gleichzeitig scheinen sie die eigentliche Dokumentation zu ersetzen.
    Alle Designdokumente sind fast schon veraltet, sobald sie fertig sind, aber Teams verweisen auf diese Designdokumente, statt neue Dokumentation zu schreiben. Dadurch ist die Dokumentation bei Google ziemlich schlecht und veraltet.
    Ehrlich gesagt wäre es viel besser gewesen, wenn als Beförderungsmaterial eine zweiseitige Anleitung gegolten hätte, wie etwas tatsächlich Existierendes verwendet wird, statt 20 Seiten darüber zu schreiben, was man „nicht gemacht hat“

  • Kann man echte Dokumente sehen? Dokumente zum Software-Designprozess wirken wie das am strengsten gehütete Geheimnis. Ich habe noch nie ein echtes Dokument gesehen, das man als Fallstudie verwenden könnte.