von Angela Zhang
Als software-Ingenieur, verbringe ich viel Zeit mit dem Lesen und schreiben von design-Dokumenten. Nachdem ich Hunderte dieser Dokumente durchgesehen habe, habe ich aus erster Hand eine starke Korrelation zwischen guten Designdokumenten und dem endgültigen Erfolg des Projekts gesehen.
Dieser Artikel ist mein Versuch zu beschreiben, was ein Designdokument großartig macht.,
Der Artikel ist in 4 Abschnitte unterteilt:
- Warum ein Designdokument schreiben
- Was in ein Designdokument aufnehmen
- Wie schreibe ich es
- Der Prozess um es herum
Warum ein Designdokument schreiben?
Ein Designdokument — auch als technische Spezifikation bekannt-beschreibt, wie Sie ein Problem lösen möchten.
Es gibt bereits viele Schriften darüber, warum es wichtig ist, ein Designdokument zu schreiben, bevor Sie in die Codierung eintauchen. Alles, was ich hier sagen werde, ist:
Ein Designdokument ist das nützlichste Werkzeug, um sicherzustellen, dass die richtige Arbeit erledigt wird.,
Das Hauptziel eines Designdokuments besteht darin, Sie effektiver zu machen, indem Sie gezwungen werden, über das Design nachzudenken und Feedback von anderen zu erhalten. Die Leute denken oft, dass der Sinn eines Designdokuments darin besteht, anderen etwas über ein System beizubringen oder später als Dokumentation zu dienen. Während diese positive Nebenwirkungen sein können, sind sie nicht das Ziel an und für sich.
Wenn Sie an einem Projekt arbeiten, das 1 Ingenieurmonat oder länger dauern kann, sollten Sie als allgemeine Faustregel ein Designdokument schreiben. Aber hören Sie nicht damit auf — viele kleinere Projekte könnten auch von einem Mini-Design-Doc profitieren.
Toll!, Wenn Sie noch lesen, glauben Sie an die Bedeutung von Designdokumenten. Verschiedene Engineering-Teams und sogar Ingenieure innerhalb desselben Teams schreiben jedoch häufig Designdokumente sehr unterschiedlich. Lassen Sie uns also über den Inhalt, den Stil und den Prozess eines guten Designdokuments sprechen.
Was in a design doc?
Ein Designdokument beschreibt die Lösung eines Problems. Da die Art jedes Problems unterschiedlich ist, möchten Sie Ihr Designdokument natürlich anders strukturieren.,
Um zu beginnen, ist das Folgende eine Liste von Abschnitten, die Sie zumindest in Betracht ziehen sollten, in Ihr nächstes Designdokument aufzunehmen:
Titel und Personen
Der Titel Ihres Designdokuments, der Autor(en) (sollte der gleiche sein wie die Liste der Personen, die planen, an diesem Projekt zu arbeiten), der / die Prüfer(en) des Dokuments (wir werden mehr darüber im Prozessabschnitt unten sprechen) und das Datum, an dem dieses Dokument zuletzt aktualisiert wurde.
Übersicht
Eine Zusammenfassung auf hoher Ebene, die jeder Ingenieur im Unternehmen verstehen und verwenden sollte, um zu entscheiden, ob es für ihn nützlich ist, den Rest des Dokuments zu lesen., Es sollten maximal 3 Absätze sein.
Kontext
Eine Beschreibung des Problems, warum dieses Projekt notwendig ist, was die Leute wissen müssen, um dieses Projekt zu bewerten, und wie es in die technische Strategie, Produktstrategie oder die vierteljährlichen Ziele des Teams passt.,
Ziele und Nicht-Ziele
Der Abschnitt Ziele sollte:
- Beschreiben Sie die benutzergesteuerten Auswirkungen Ihres Projekts-wobei Ihr Benutzer möglicherweise ein anderes Engineering-Team oder sogar ein anderes technisches System ist
- Geben Sie an, wie Sie den Erfolg mithilfe von Metriken messen können — Bonuspunkte, wenn Sie auf ein Dashboard verlinken können, das diese Metriken verfolgt
Nicht-Ziele sind ebenso wichtig, um zu beschreiben, welche Probleme Sie nicht beheben werden, sodass sich alle auf derselben Seite befinden.,
Meilensteine
Eine Liste messbarer Checkpoints, damit Ihr PM und der Manager Ihres Managers sie überspringen und ungefähr wissen können, wann verschiedene Teile des Projekts ausgeführt werden. Ich ermutige Sie, das Projekt in wichtige Meilensteine für Benutzer aufzuteilen, wenn das Projekt mehr als 1 Monat lang ist.
Verwenden Sie Kalenderdaten, um nicht zusammenhängende Verzögerungen, Ferien, Besprechungen usw. zu berücksichtigen., Es sollte ungefähr so aussehen:
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
Fügen Sie hier einen Unterabschnitt hinzu, wenn die ETA einiger dieser meilensteinänderungen, so dass die Stakeholder leicht die aktuellsten Schätzungen sehen können.
Vorhandene Lösung
Zusätzlich zur Beschreibung der aktuellen Implementierung sollten Sie auch einen hochrangigen Beispielfluss durchlaufen, um zu veranschaulichen, wie Benutzer mit diesem System interagieren und/oder wie Daten durch dieses fließen.,
Eine User Story ist eine großartige Möglichkeit, dies zu gestalten. Beachten Sie, dass Ihr System möglicherweise verschiedene Arten von Benutzern mit unterschiedlichen Anwendungsfällen hat.
Lösungsvorschlag
Einige Leute nennen dies den Abschnitt Technische Architektur. Versuchen Sie erneut, eine Benutzergeschichte zu durchlaufen, um dies zu konkretisieren. Fühlen Sie sich frei, viele Unterabschnitte und Diagramme aufzunehmen.
Geben Sie zuerst ein großes Bild an und geben Sie dann viele Details ein. Zielen Sie auf eine Welt, in der Sie dies schreiben können, und machen Sie dann Urlaub auf einer einsamen Insel, und ein anderer Ingenieur im Team kann es einfach lesen und die von Ihnen beschriebene Lösung implementieren.,
Alternative Lösungen
Was haben Sie bei der obigen Lösung noch berücksichtigt? Was sind die Vor – und Nachteile der Alternativen? Haben Sie überlegt, eine Lösung von Drittanbietern zu kaufen-oder eine Open — Source — Lösung zu verwenden -, die dieses Problem löst, anstatt eine eigene zu erstellen?
Testbarkeit, Überwachung und Alarmierung
Ich mag es, diesen Abschnitt einzuschließen, weil die Leute dies oft als nachträglichen Einfall behandeln oder alles zusammen überspringen, und es kommt fast immer zurück, um sie später zu beißen, wenn die Dinge kaputt gehen und sie keine Ahnung haben, wie oder warum.,
Teamübergreifende Wirkung
Wie wird dies bei Call-und Dev-Ops-Belastungen zunehmen?
Wie viel Geld wird es Kosten?
Verursacht es eine Latenzregression für das System?
Hat es keine Sicherheitslücken aussetzen?
Was sind einige negative Folgen und Nebenwirkungen?
Wie könnte das Support-Team dies den Kunden mitteilen?
Offene Fragen
Alle offenen Fragen, über die Sie sich nicht sicher sind, strittige Entscheidungen, die die Leser abwägen sollen, vorgeschlagene zukünftige Arbeit und so weiter. Ein augenzwinkernder Name für diesen Abschnitt sind die „bekannten Unbekannten“.,
Detaillierter Bereich und Zeitleiste
Dieser Abschnitt wird hauptsächlich nur von den Ingenieuren gelesen, die an diesem Projekt arbeiten, ihren technischen Leads und ihren Managern. Daher befindet sich dieser Abschnitt am Ende des Dokuments.
Im Wesentlichen ist dies die Aufschlüsselung, wie und wann Sie die Ausführung jedes Teils des Projekts planen. Es gibt eine Menge, die genau in das Scoping geht, also können Sie diesen Beitrag lesen, um mehr über das Scoping zu erfahren.
Ich neige dazu, diesen Abschnitt des Designdokuments auch als laufenden Projekt-Task-Tracker zu behandeln, daher aktualisiere ich diesen, wenn sich meine Bereichsschätzung ändert., Aber das ist eher eine persönliche Präferenz.
How to write it
Jetzt, wir haben auch darüber gesprochen, was in ein gutes design doc, reden wir über den Stil des Schreibens. Ich verspreche, das ist anders als deine Highschool-Englischklasse.
Schreiben Sie so einfach wie möglich
Versuchen Sie nicht, wie die akademischen Arbeiten zu schreiben, die Sie gelesen haben. Sie sind geschrieben, um Zeitschriftenprüfer zu beeindrucken. Ihr Dokument wird geschrieben, um Ihre Lösung zu beschreiben und Feedback von Ihren Teamkollegen zu erhalten., Sie können Klarheit erreichen, indem Sie:
- Einfache Wörter
- Kurze Sätze
- Aufzählungslisten und/oder nummerierte Listen
- Konkrete Beispiele wie „Benutzer Alice verbindet ihr Bankkonto, dann …“
Fügen Sie viele Diagramme und Diagramme hinzu
Diagramme können oft nützlich sein, um mehrere potenzielle Optionen zu vergleichen, und Diagramme sind im Allgemeinen einfacher zu analysieren als Text. Ich hatte viel Glück mit Google Drawing zum Erstellen von Diagrammen.,
Pro-Tipp: Denken Sie daran, unter dem Screenshot einen Link zur bearbeitbaren Version des Diagramms hinzuzufügen, damit Sie es später leicht aktualisieren können, wenn sich die Dinge zwangsläufig ändern.
Zahlen einschließen
Der Umfang des Problems bestimmt häufig die Lösung. Um Rezensenten ein Gefühl für den Zustand der Welt zu vermitteln, fügen Sie reelle Zahlen wie # der DB — Zeilen, # der Benutzerfehler, Latenz ein-und wie diese mit der Verwendung skaliert werden. Erinnerst du dich an deine Big-O-Notationen?
Versuche lustig zu sein
Eine Spezifikation ist keine akademische Arbeit. Außerdem lesen die Leute gerne lustige Dinge, also ist dies ein guter Weg, um den Leser zu beschäftigen., Übertreiben Sie dies jedoch nicht so weit, dass Sie sich von der Grundidee entfernen.
Wenn Sie, wie ich, Schwierigkeiten haben, lustig zu sein, hat Joel Spolsky (offensichtlich bekannt für seine komödiantischen Talente…) diesen Tipp:
Eine der einfachsten Möglichkeiten, lustig zu sein, besteht darin, spezifisch zu sein, wenn es nicht verlangt wird, anstatt „besondere Interessen“ zu sagen, sagen Sie „Linkshänder avacado“.“
Führen Sie den skeptischen Test durch
Bevor Sie Ihr Designdokument zur Überprüfung an andere senden, machen Sie einen Pass und geben Sie vor, der Rezensent zu sein. Welche Fragen und Zweifel könnten Sie an diesem Design haben?, Dann sprechen Sie sie präventiv an.
Machen Sie den Urlaubstest
Wenn Sie jetzt ohne Internetzugang in einen langen Urlaub fahren, kann jemand in Ihrem Team das Dokument lesen und es wie beabsichtigt implementieren?
Das Hauptziel eines Designdokuments ist nicht der Wissensaustausch, aber dies ist ein guter Weg, um Klarheit zu schaffen, damit andere Ihnen tatsächlich nützliches Feedback geben können.
Prozess
Ah ja, das gefürchtete P-Wort., Design-Dokumente helfen Ihnen, Feedback zu erhalten, bevor Sie eine Menge Zeit damit verschwenden, die falsche Lösung oder die Lösung für das falsche Problem zu implementieren. Es gibt eine Menge Kunst, gutes Feedback zu bekommen, aber das ist für einen späteren Artikel. Lassen Sie uns im Moment nur speziell darüber sprechen, wie Sie das Design-Dokument schreiben und Feedback dafür erhalten.
Zunächst sollte jeder, der an dem Projekt arbeitet, Teil des Entwurfsprozesses sein. Es ist in Ordnung, wenn der Tech-Lead am Ende viele Entscheidungen trifft, aber jeder sollte in die Diskussion einbezogen werden und sich für das Design interessieren., Das “ Sie „in diesem Artikel ist also ein wirklich plurales“ Sie“, das alle Personen im Projekt einschließt.
Zweitens bedeutet der Designprozess nicht, dass Sie auf das Whiteboard starren und Ideen theoretisieren. Fühlen Sie sich frei, sich die Hände schmutzig zu machen und mögliche Lösungen zu prototypen. Dies ist nicht dasselbe wie das Schreiben von Produktionscode für das Projekt vor dem Schreiben eines Designdokuments. Tu das nicht. Aber Sie sollten sich absolut frei fühlen, einen hackigen Wegwerfcode zu schreiben, um eine Idee zu validieren., Um sicherzustellen, dass Sie nur explorativen Code schreiben, machen Sie es zu einer Regel, dass keiner dieser Prototypcodes zum Master zusammengeführt wird.
Danach, wenn Sie eine Vorstellung davon haben, wie Sie mit Ihrem Projekt umgehen sollen, gehen Sie wie folgt vor:
- Bitten Sie einen erfahrenen Ingenieur oder technischen Leiter in Ihrem Team, Ihr Rezensent zu sein. Idealerweise wäre dies jemand, der mit den Randfällen des Problems gut respektiert und/oder vertraut ist. Bestechen Sie sie bei Bedarf mit Boba.
- Gehen Sie in einen Konferenzraum mit einem Whiteboard.,
- Beschreiben Sie das Problem, das Sie mit diesem Ingenieur angehen (dies ist ein sehr wichtiger Schritt, überspringen Sie es nicht!).
- Erklären Sie dann die Implementierung, die Sie im Sinn haben, und überzeugen Sie sie, dass dies das Richtige ist.
Wenn Sie all dies tun, bevor Sie überhaupt mit dem Schreiben Ihres Designdokuments beginnen, erhalten Sie so schnell wie möglich Feedback, bevor Sie mehr Zeit investieren und sich an eine bestimmte Lösung binden., Selbst wenn die Implementierung gleich bleibt, kann Ihr Prüfer häufig darauf hinweisen, welche Fälle Sie abdecken müssen, mögliche Verwirrungsbereiche angeben und Schwierigkeiten antizipieren, auf die Sie später stoßen könnten.
Nachdem Sie einen groben Entwurf Ihres Designdokuments geschrieben haben, lassen Sie denselben Prüfer erneut durchlesen und stempeln Sie ihn, indem Sie seinen Namen als Prüfer im Abschnitt Titel und Personen des Designdokuments hinzufügen. Dies schafft zusätzliche Anreize und Verantwortlichkeit für den Prüfer.,
In diesem Sinne sollten Sie spezielle Prüfer (wie SREs und Sicherheitsingenieure) für bestimmte Aspekte des Designs hinzufügen.
Sobald Sie und der / die Rezensenten sich abmelden, können Sie das Designdokument an Ihr Team senden, um zusätzliches Feedback und Wissensaustausch zu erhalten. Ich schlage vor, diesen Feedback-Sammelprozess auf etwa 1 Woche zu begrenzen, um längere Verzögerungen zu vermeiden. Verpflichten, auf alle Fragen und Kommentare verlassen die Menschen innerhalb dieser Woche. Kommentare hängen lassen = schlechtes Karma.,
Wenn es zwischen Ihnen, Ihrem Rezensenten und anderen Ingenieuren, die das Dokument lesen, große Konflikte gibt, empfehle ich dringend, alle Streitpunkte im Diskussionsbereich Ihres Dokuments zu konsolidieren. Richten Sie dann ein Treffen mit den verschiedenen Parteien ein, um persönlich über diese Meinungsverschiedenheiten zu sprechen.
Wenn ein Diskussionsthread mehr als 5 Kommentare lang ist, ist der Wechsel zu einer persönlichen Diskussion in der Regel weitaus effizienter. Denken Sie daran, dass Sie immer noch für den letzten Anruf verantwortlich sind, auch wenn nicht alle zu einem Konsens kommen können.,
Als ich kürzlich mit Shrey Banga darüber sprach, erfuhr ich, dass Quip einen ähnlichen Prozess hat, außer dass sie nicht nur einen erfahrenen Ingenieur oder technischen Leiter in Ihrem Team als Rezensenten haben, sondern auch einen Ingenieur in einem anderen Team, der das Dokument überprüft. Ich habe das nicht versucht, aber ich kann sicherlich sehen, dass dies dazu beiträgt, Feedback von Menschen mit unterschiedlichen Perspektiven zu erhalten und die allgemeine Lesbarkeit des Dokuments zu verbessern.
Sobald Sie alle oben genannten getan haben, Zeit, um auf die Umsetzung los!, Behandeln Sie dieses Designdokument bei der Implementierung des Designs für zusätzliche Brownie-Punkte als lebendes Dokument. Aktualisieren Sie das Dokument jedes Mal, wenn Sie etwas erfahren, das dazu führt, dass Sie Änderungen an der ursprünglichen Lösung vornehmen oder Ihren Bereich aktualisieren. Du wirst es mir später danken, wenn du es nicht immer wieder deinen Stakeholdern erklären musst.
Lassen Sie uns schließlich für eine Sekunde wirklich Meta werden: Wie bewerten wir den Erfolg eines Designdokuments?
Mein Mitarbeiter Kent Rakip hat darauf eine gute Antwort: Ein Design-Doc ist erfolgreich, wenn der richtige ROI der Arbeit geleistet wird.,ts der technischen Architektur
X der riskanteste Teil der vorgeschlagenen Architektur istX Um das Projekt zunächst zu de-riskierenX entweder nicht möglich oder weitaus schwieriger ist, als ursprünglich beabsichtigtAm Anfang dieses Artikels haben wir gesagt, dass das Ziel eines Designdokuments darin besteht, sicherzustellen, dass die richtige Arbeit erledigt wird., Im obigen Beispiel haben Sie dank dieses Entwurfsdokuments nur 8 Tage verbracht, anstatt 6 Monate zu verschwenden, um dieses Projekt später abzubrechen. Scheint mir ein ziemlich erfolgreiches Ergebnis zu sein.
Bitte hinterlassen Sie unten einen Kommentar, wenn Sie Fragen oder Feedback haben! Ich würde auch gerne hören, wie Sie Dokumente in Ihrem Team anders gestalten.
Kredit geben, wo Kredit fällig ist, habe ich viel davon gelernt, indem ich mit einigen unglaublichen Ingenieuren bei Plaid zusammengearbeitet habe (wir stellen ein! Kommen Sie Design und bauen einige süße technische Systeme mit uns) und Quora.,
Wenn Ihnen dieser Beitrag gefällt, folgen Sie mir auf Twitter für weitere Beiträge zu Engineering, Prozessen und Backend-Systemen.