Wie schreibe ich ein gutes Software-Design-Dokument?

Als Softwareentwickler verbringe ich viel Zeit mit dem Lesen und Schreiben von Designdokumenten. 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 soll in ein Designdokument aufgenommen werden ?
  • Wie schreibe ich es?
  • Der Prozess um ihn herum

Warum ein Designdokument schreiben?

Ein Konstruktionsdokument - auch als technische Spezifikation bezeichnet - 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 sich mit dem Codieren befassen. Alles was ich hier sagen werde ist:

Ein Konstruktionsdokument 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, das Design zu durchdenken und Feedback von anderen einzuholen. Die Leute denken oft, dass der Sinn eines Designdokuments darin besteht, andere über ein System zu unterrichten oder später als Dokumentation zu dienen. Während diese vorteilhaften Nebenwirkungen sein können, sind sie nicht das Ziel an und für sich.

Als Faustregel gilt: Wenn Sie an einem Projekt arbeiten, das 1 Ingenieurmonat oder länger dauern kann, sollten Sie ein Konstruktionsdokument schreiben. Aber hören Sie hier nicht auf - viele kleinere Projekte könnten auch von einem Mini-Design-Dokument profitieren.

Toll! Wenn Sie noch lesen, glauben Sie an die Bedeutung von Designdokumenten. Unterschiedliche Entwicklungsteams und sogar Ingenieure innerhalb desselben Teams schreiben Konstruktionsdokumente jedoch häufig sehr unterschiedlich. Sprechen wir also über Inhalt, Stil und Prozess eines guten Designdokuments.

Was soll in ein Designdokument aufgenommen werden?

Ein Konstruktionsdokument beschreibt die Lösung eines Problems. Da die Art jedes Problems unterschiedlich ist, möchten Sie Ihr Designdokument natürlich anders strukturieren.

Im Folgenden finden Sie eine Liste von Abschnitten, die Sie zumindest berücksichtigen solltenEinschließlich in Ihrem nächsten Designdokument:

Titel und Personen

Der Titel Ihres Designdokuments, derAutor (en) (sollte mit der Liste der Personen übereinstimmen, die an diesem Projekt arbeiten möchten), der / die Rezensent (en)des Dokuments (mehr dazu im Abschnitt "Prozess" weiter unten) und das Datum, an dem dieses Dokument zuletzt aktualisiert wurde.

Überblick

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 vorliegenden 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 Nichtziele

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 der Erfolg mithilfe von Metriken gemessen werden soll - Bonuspunkte, wenn Sie eine Verknüpfung zu einem Dashboard herstellen können, das diese Metriken verfolgt

Nicht-Ziele sind ebenso wichtig, um zu beschreiben, welche Probleme Sie nicht beheben werden, damit alle auf derselben Seite sind.

Meilensteine

Eine Liste messbarer Kontrollpunkte, damit Ihr PM und der Manager Ihres Managers sie überfliegen und ungefähr wissen können, wann verschiedene Teile des Projekts durchgeführt werden. Ich empfehle Ihnen, das Projekt in wichtige Meilensteine ​​für Benutzer zu unterteilen, wenn das Projekt länger als einen Monat dauert.

Verwenden Sie Kalenderdaten, um Verzögerungen, Urlaube, Besprechungen usw. zu berücksichtigen. Es sollte ungefähr so ​​aussehen:

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

Fügen Sie hier einen [Update]Unterabschnitt hinzu, wenn sich die ETA einiger dieser Meilensteine ​​ändert, damit die Stakeholder leicht die aktuellsten Schätzungen sehen können.

Bestehende Lösung

Zusätzlich zur Beschreibung der aktuellen Implementierung sollten Sie einen allgemeinen Beispielfluss durchlaufen, um zu veranschaulichen, wie Benutzer mit diesem System interagieren und / oder wie Daten durch dieses System fließen.

Ein BenutzerGeschichteist eine großartige Möglichkeit, dies zu gestalten. Beachten Sie, dass Ihr System möglicherweise unterschiedliche Benutzertypen mit unterschiedlichen Anwendungsfällen hat.

Vorgeschlagene Lösung

Einige Leute nennen dies den Abschnitt Technische Architektur . Versuchen Sie erneut, eine User Story durchzugehen, um dies zu konkretisieren. Fühlen Sie sich frei, viele Unterabschnitte und Diagramme aufzunehmen.

Stellen Sie zuerst ein großes Bild bereit und füllen Sie dann die Lose ausvonEinzelheiten. Streben Sie eine Welt an, in der Sie dies schreiben und dann auf einer einsamen Insel Urlaub machen können, und ein anderer Ingenieur im Team kann es einfach lesen und die von Ihnen beschriebene Lösung implementieren.

Alternativlösungen

Was haben Sie noch berücksichtigt, als Sie die obige Lösung gefunden haben? Was sind die Vor- und Nachteile der Alternativen? Haben Sie darüber nachgedacht, eine Drittanbieterlösung 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 aufzunehmen, weil die Leute dies oft als nachträglichen Gedanken behandeln oder alles zusammen überspringen und es fast immer zurückkommt, um sie später zu beißen, wenn die Dinge kaputt gehen und sie keine Ahnung haben, wie oder warum.

Teamübergreifende Auswirkungen

Wie wird sich diese Belastung durch Bereitschafts- und Entwicklungsarbeiten erhöhen?

Wie viel Geld wird es kosten?

Verursacht es eine Latenzregression für das System?

Gibt es Sicherheitslücken?

Was sind einige negative Folgen und Nebenwirkungen?

Wie könnte das Support-Team dies den Kunden mitteilen?

Offene Fragen

Alle offenen Fragen, bei denen Sie sich nicht sicher sind, umstrittene Entscheidungen, die die Leser abwägen sollen, Vorschläge für zukünftige Arbeiten usw. Ein ironischer Name für diesen Abschnitt sind die „bekannten Unbekannten“.

Detailliertes Scoping und Timeline

Dieser Abschnitt wird hauptsächlich von den an diesem Projekt beteiligten Ingenieuren, ihren technischen Leitern und ihren Managern gelesen. Daher befindet sich dieser Abschnitt am Ende des Dokuments.

Dies ist im Wesentlichen die Aufschlüsselung, wie und wann Sie die einzelnen Teile des Projekts ausführen möchten. Es gibt eine Menge, die genau in das Scoping einfließen. Sie können diesen Beitrag lesen, um mehr über das Scoping zu erfahren.

Ich neige dazu, diesen Abschnitt des Entwurfsdokuments auch als fortlaufenden Projektaufgaben-Tracker zu behandeln. Daher aktualisiere ich diesen Abschnitt, wenn sich meine Schätzung des Umfangs ändert. Aber das ist eher eine persönliche Präferenz.

Wie schreibe ich es?

Nachdem wir darüber gesprochen haben, was in einem guten Designdokument steckt, lassen Sie uns über den Schreibstil sprechen. Ich verspreche, dass dies anders ist als Ihr Englischunterricht an der High School.

Schreiben Sie so einfach wie möglich

Versuchen Sie nicht, wie die akademischen Arbeiten zu schreiben, die Sie gelesen haben. Sie wurden geschrieben, um Journal-Rezensenten zu beeindrucken. Ihr Dokument wurde geschrieben, um Ihre Lösung zu beschreiben und Feedback von Ihren Teamkollegen zu erhalten. Sie können Klarheit erreichen, indem Sie Folgendes verwenden:

  • Einfache Worte
  • Kurze Sätze
  • Listen mit Aufzählungszeichen 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 mögliche Optionen zu vergleichen, und Diagramme sind im Allgemeinen einfacher zu analysieren als Text. Ich hatte viel Glück mit Google Drawing beim Erstellen von Diagrammen.

Pro-Tipp: Denken Sie daran, einen Link zur bearbeitbaren Version des Diagramms unter dem Screenshot hinzuzufügen, damit Sie es später problemlos aktualisieren können, wenn sich Änderungen zwangsläufig ändern.

Zahlen einschließen

Das Ausmaß des Problems bestimmt häufig die Lösung. Geben Sie reelle Zahlen wie Anzahl der DB-Zeilen, Anzahl der Benutzerfehler, Latenz - und wie diese mit der Nutzung skalieren, um den Prüfern ein Gefühl für den Zustand der Welt zu vermitteln. Erinnerst du dich an deine Big-O-Notationen?

Versuche lustig zu sein

Eine Spezifikation ist keine wissenschaftliche Arbeit. Außerdem lesen die Leute gerne lustige Dinge, daher ist dies eine gute Möglichkeit, den Leser zu beschäftigen. Übertreiben Sie dies jedoch nicht, bis Sie die Kernidee verlassen.

Wenn Sie wie ich Probleme haben, lustig zu sein, hat Joel Spolsky ( offensichtlich bekannt für seine komödiantischen Talente…) diesen Tipp:

Eine der einfachsten Möglichkeiten , um lustig zu sein ist zu spezifisch , wenn es nicht aufgerufen wird für [... Beispiel:] Anstatt zu sagen „Sonderinteressen“ , sagen „linkshändig avacado Bauern.“

Machen Sie den Skeptiktest

Bevor Sie Ihr Designdokument zur Überprüfung an andere senden, versuchen Sie es als Prüfer. Welche Fragen und Zweifel könnten Sie zu diesem Design haben? Dann sprechen Sie sie präventiv an.

Machen Sie den Urlaubstest

Wenn Sie jetzt einen langen Urlaub ohne Internetzugang verbringen, kann jemand in Ihrem Team das Dokument lesen und es wie beabsichtigt implementieren?

Das Hauptziel eines Designdokuments ist nicht der Wissensaustausch. Dies ist jedoch eine gute Möglichkeit, die Klarheit zu überprüfen, damit andere Ihnen tatsächlich nützliches Feedback geben können.

Prozess

Ach ja, das gefürchtete P-Wort . Mithilfe von Designdokumenten erhalten Sie Feedback, bevor Sie viel Zeit damit verschwenden, die falsche Lösung oder die Lösung für das falsche Problem zu implementieren. Es ist eine Menge Kunst, gutes Feedback zu bekommen, aber das ist für einen späteren Artikel. Lassen Sie uns zunächst speziell darüber sprechen, wie Sie das Designdokument schreiben und Feedback dazu erhalten.

Zunächst sollte jeder, der an dem Projekt arbeitet, Teil des Entwurfsprozesses sein. Es ist in Ordnung, wenn der technische Leiter viele Entscheidungen trifft, aber jeder sollte in die Diskussion einbezogen werden und sich an dem Design beteiligen. Das „Sie“ in diesem Artikel ist also ein wirklich pluralistisches „Sie“, das alle Personen des Projekts umfasst.

Zweitens bedeutet der Entwurfsprozess nicht, dass Sie auf die Whiteboard-Theoretisierungsideen starren. Fühlen Sie sich frei, sich die Hände schmutzig zu machen und mögliche Lösungen zu entwickeln. Dies ist nicht gleichbedeutend mit dem Schreiben des Produktionscodes für das Projekt vor dem Schreiben eines Konstruktionsdokuments. Tu das nicht. Aber Sie sollten sich unbedingt frei fühlen, einen hackigen Wegwerfcode zu schreiben, um eine Idee zu validieren. Um sicherzustellen, dass Sie nur explorativen Code schreiben, legen Sie die Regel fest, dass keiner dieser Prototypcodes zum Master zusammengeführt wird .

Gehen Sie danach wie folgt vor, wenn Sie eine Vorstellung davon haben, wie Sie Ihr Projekt durchführen sollen:

  1. Bitten Sie einen erfahrenen Ingenieur oder technischen Leiter Ihres Teams, Ihr Prüfer zu sein. Im Idealfall ist dies jemand, der die Randfälle des Problems respektiert und / oder kennt. Besteche sie bei Bedarf mit Boba.
  2. Gehen Sie in einen Konferenzraum mit einem Whiteboard.
  3. Beschreiben Sie das Problem , das Sie mit diesem Techniker angehen (dies ist ein sehr wichtiger Schritt, überspringen Sie ihn nicht!).
  4. Erklären Sie dann die Implementierung, an die Sie denken, und überzeugen Sie sie davon, dass dies das Richtige ist.

Wenn Sie dies alles 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 auf Eckfälle hinweisen, die Sie abdecken müssen, auf mögliche Verwirrungsbereiche hinweisen und Schwierigkeiten antizipieren, auf die Sie später stoßen könnten.

Nachdem Sie einen groben Entwurf Ihres Konstruktionsdokuments geschrieben haben, lassen Sie denselben Prüfer ihn erneut durchlesen und stempeln Sie ihn ab, indem Sie seinen Namen als Prüfer im Abschnitt Titel und Personen des Konstruktionsdokuments hinzufügen . Dies schafft zusätzlichen Anreiz und Verantwortlichkeit für den Prüfer.

In diesem Zusammenhang sollten Sie spezielle Prüfer (z. B. SREs und Sicherheitsingenieure) für bestimmte Aspekte des Entwurfs hinzufügen.

Sobald Sie und die Prüfer sich abgemeldet haben, können Sie das Designdokument an Ihr Team senden, um zusätzliches Feedback und Wissensaustausch zu erhalten. Ich empfehle, diesen Feedback-Erfassungsprozess auf etwa 1 Woche zu beschränken, um längere Verzögerungen zu vermeiden. Verpflichten Sie sich, alle Fragen und Kommentare zu beantworten, die die Leute innerhalb dieser Woche hinterlassen. Kommentare hängen lassen = schlechtes Karma.

Wenn zwischen Ihnen, Ihrem Prüfer und anderen Ingenieuren, die das Dokument lesen, viele Konflikte bestehen, empfehle ich dringend, alle Streitpunkte im Abschnitt " Diskussion " Ihres Dokuments zu konsolidieren . Vereinbaren Sie dann ein Treffen mit den verschiedenen Parteien, um persönlich über diese Meinungsverschiedenheiten zu sprechen.

Wenn ein Diskussionsthread länger als 5 Kommentare ist, ist der Wechsel zu einer persönlichen Diskussion in der Regel weitaus effizienter. Denken Sie daran, dass Sie weiterhin 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 ein erfahrener Ingenieur oder technischer Leiter in Ihrem Team als Prüfer tätig ist. Außerdem wird vorgeschlagen, dass ein Ingenieur in einem anderen Team das Dokument überprüft. Ich habe dies nicht ausprobiert, aber ich kann sicher sehen, dass dies dazu beiträgt, Feedback von Personen mit unterschiedlichen Perspektiven zu erhalten und die allgemeine Lesbarkeit des Dokuments zu verbessern.

Sobald Sie alle oben genannten Schritte ausgeführt haben, können Sie mit der Implementierung beginnen! Behandeln Sie dieses Designdokument für zusätzliche Brownie-Punkte als lebendes Dokument, wenn Sie das Design implementieren . 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 Umfang aktualisieren. Sie werden mir später danken, wenn Sie nicht allen Ihren Stakeholdern immer wieder Dinge erklären müssen.

Lassen Sie uns zum Schluss für eine Sekunde wirklich Meta bekommen : Wie bewerten wir den Erfolg eines Designdokuments?

Mein Kollege Kent Rakip hat eine gute Antwort darauf: Ein Designdokument ist erfolgreich, wenn der richtige ROI der Arbeit erzielt wird. Das bedeutet, dass ein erfolgreiches Designdokument tatsächlich zu einem Ergebnis wie dem folgenden führen kann:

  1. Sie schreiben 5 Tage lang das Designdokument. Dies zwingt Sie dazu, verschiedene Teile der technischen Architektur zu durchdenken
  2. Sie erhalten Feedback von Gutachtern, Xdas der riskanteste Teil der vorgeschlagenen Architektur ist
  3. Sie entscheiden sich, Xzuerst zu implementieren, um das Risiko des Projekts zu verringern
  4. 3 Tage später stellen Sie fest, dass dies Xentweder nicht möglich oder weitaus schwieriger ist als ursprünglich beabsichtigt
  5. Sie beschließen, die Arbeit an diesem Projekt einzustellen und stattdessen andere Arbeiten zu priorisieren

Am 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 potenziell 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.

Ich habe Kredit gegeben, wo Kredit fällig ist, und viel gelernt, indem ich mit einigen unglaublichen Ingenieuren bei Plaid (wir stellen ein! Entwerfen und bauen Sie mit uns einige süße technische Systeme) und Quora zusammengearbeitet habe.

Wenn Ihnen dieser Beitrag gefällt, folgen Sie mir auf Twitter, um weitere Beiträge zu Engineering, Prozessen und Backend-Systemen zu erhalten.