Erstellen und Verwenden von Konstruktionsdokumentationen bei Neon

Es gibt viele Quellen zum Thema Design, aber in diesem Artikel möchte ich mich darauf konzentrieren, das Framework zu beschreiben, das wir bei Neon verwenden, um Designs zu bewerten und das für unsere Bedürfnisse am besten geeignete auszuwählen. Lesen Sie also weiter, um mehr über unsere Designdokumentation und die von uns empfohlenen Best Practices zu erfahren.

Bei Neon wollten wir sicherstellen, dass wir eine konstruktive Diskussion über wichtige Änderungen an unserem System führen und gemeinsam Entscheidungen treffen können. Wir wollten Situationen vermeiden, in denen Entscheidungen stark zentralisiert sind und Ingenieure das Gefühl haben, dass sie kein Feedback zu einer bestimmten Lösung geben können (oder diese in einigen Fällen vielleicht sogar infrage stellen). Dies wird umso wichtiger, je grösser das Team wird und je mehr neue Ingenieure zum Team hinzukommen. Mit diesem Rahmenwerk und der Designdokumentation (wir nennen es intern D&A) ist uns genau das mit grossem Erfolg gelungen.

Wie unser Designprozess aussieht

Kurz gesagt, eine Person beschreibt die Idee (Design) strukturiert und versucht, genügend Informationen zu liefern, um sie zu begründen. Dann gibt der Rest des Teams Feedback und diskutiert verschiedene Aspekte des Designs, um schliesslich zu entscheiden, ob es sich lohnt, das Design umzusetzen oder nicht. Das ist jedoch nur die Kurzfassung, in Wirklichkeit ist es (wie immer) etwas komplexer.

Das Framework selbst besteht aus zwei Hauptteilen: Der erste Teil ist die Design-Dokumentation, die alle wichtigen Informationen zum Design enthält. Der andere Teil ist der Prozess, der dazu dient, Feedback zu geben und eine Entscheidung zu treffen.

Teil 1: Die Designdokumentation

Sehen wir uns nun die Vorlage für die Design-Dokumentation an, die wir bei Neon verwenden. Sie besteht aus mehreren wichtigen Teilen:

• Ziel
• Problemstellung
• Aktueller Stand
• Umfang
• Design und Alternativen
• Massnahmen

Nachfolgend finden Sie eine detaillierte Beschreibung der einzelnen Teile der Designvorlage sowie Tipps, wie Sie Ihre Designdokumentation optimal nutzen können.

Ziel

Hier müssen Sie kurz das Ziel des Designs definieren – was Sie damit erreichen möchten. Zum Beispiel: „Wir möchten eine Funktion für gemeinsame Konten entwickeln. Diese Funktion richtet sich an Benutzer, die ein Konto für verschiedene Zwecke wie Familienausgaben oder Ersparnisse gemeinsam nutzen möchten.“

Die Problemstellung

Hier müssen Sie das Problem beschreiben, das Sie lösen möchten, und erklären, warum Sie es als Problem betrachten. Beispiel: „Wir möchten den Dienst X in zwei kleinere Dienste aufteilen. Derzeit verfügt der Dienst X über viele Funktionen. Alle diese Funktionen lassen sich in zwei unterschiedliche Gruppen unterteilen. Eine dieser Gruppen wird aktiv weiterentwickelt, während die andere stabil ist und nur gelegentlich geändert wird. Durch die Aufteilung des Dienstes X in zwei kleinere Dienste werden beide Dienste verständlicher und wartungsfreundlicher, sodass wir eine bessere Skalierung und eine individuellere Optimierung erzielen können.“

Der aktuelle Stand

Dies ist die Beschreibung des Designs, über das Sie derzeit verfügen. Sie sollten den Lesern Ihrer Designdokumentation ausreichende Informationen über den aktuellen Stand liefern. Dazu gehören technische Details und die wichtigsten Herausforderungen oder Einschränkungen. Fügen Sie nach Möglichkeit Diagramme, Bilder und Leistungsdaten hinzu. Was auch immer Sie für nützlich halten (je nach Fall), sollte enthalten sein. Beachten Sie, dass Sie hier präzise sein müssen, da Sie den Zustand beschreiben, den Sie ändern möchten, und warum Sie ihn ändern möchten.

Der Umfang

Beschreiben Sie, was Teil Ihrer Designdokumentation sein wird und was nicht.

Design und Alternativen

Nun kommen wir zum „Kernstück” dieser Designdokumentation – dem neuen Design, das Sie vorschlagen. Fügen Sie ausreichend relevante Informationen hinzu, vermeiden Sie jedoch zu viele technische Details, es sei denn, sie sind nötig.

Wenn wir beispielsweise das vorherige Beispiel mit den beiden neuen Diensten verwenden, die den bestehenden Dienst ersetzen sollen, sollten Sie alle Anwendungsfälle auflisten, die jeder dieser Dienste abdecken wird. Sie können eine Liste der Endpunkte bereitstellen, aber Sie müssen keine Anfragen und Antworten beschreiben, es sei denn, dies ist entscheidend. Wenn es Integration mit Systemen Dritter, Caching oder Sicherheitsaspekte gibt, sollten diese klar beschrieben werden. In einigen Fällen könnte das Design durch ein kleines Proof-of-Concept-Projekt ergänzt werden, um die Machbarkeit zu überprüfen.

Alternativen

Idealerweise folgen auf den Hauptentwurf eine oder mehrere Alternativen. Diese Alternativen berücksichtigen Faktoren wie Zeit, Umfang und Komplexität. Sie sollten Vor- und Nachteile klar auflisten. Wenn keine Zeit für das Hauptdesign bis zum Release bleibt, könnte eine Alternative darin bestehen, nur den wichtigsten Teil umzusetzen und den Rest nachzuziehen. Manchmal gibt es keine realistischen Alternativen – das hängt vom Einzelfall ab.

Weitere wichtige Aspekte

Bei der Entscheidung über das Design spielen mehrere Faktoren eine Rolle, zum Beispiel:

• Ist dies für Ihr Produkt strategisch relevant?
• Hat dies Auswirkungen auf Kunden oder die Leistung des Systems?
• Löst oder verhindert dies bestehende Engineering-Probleme?
• Ist dies nur eine kleine Verbesserung ohne grossen Effekt?

Wenn Sie all dies berücksichtigen, stellen Sie sicher, dass Sie sich zuerst auf wesentliche Entscheidungen mit grosser Wirkung konzentrieren.

Teil 2: Der Prozess

Der Prozess besteht aus mehreren Phasen:

Das Design schreiben

Hier findet der Grossteil der Arbeit statt. Eine Person sammelt alle erforderlichen Informationen und erstellt die Designdokumentation mit der oben beschriebenen Vorlage. Sobald das Dokument fertig ist, werden Reviewer eingeladen und eine Besprechung geplant. Bei Neon verwenden wir Confluence dafür, aber ähnliche Tools wie Notion sind ebenfalls geeignet.

Überprüfung

Reviewer lesen das Dokument und hinterlassen Kommentare. Dafür gilt eine Frist: bis dahin müssen alle ihr Feedback abgegeben haben. Wer kein Feedback hinterlässt, wird aus der abschliessenden Diskussion ausgeschlossen. Diskutiert wird nur mit Personen, die das Dokument tatsächlich gelesen haben.

Beantwortung der Kommentare

Der Autor beantwortet jeden Kommentar, gegebenenfalls durch Ergänzungen oder Änderungen am Dokument. Jede Antwort soll den Kommentar lösen, und der jeweilige Reviewer markiert ihn als erledigt.

Abschliessende Diskussion

Nach der Lösung aller Kommentare findet die abschliessende Diskussion statt. Alle haben das Dokument gelesen und Feedback eingearbeitet. Das Ziel: die Auswahl des besten Lösungsansatzes. Dabei wird entschieden, welcher Vorschlag umgesetzt wird und welche Schritte folgen. Der Dokumentautor muss nicht den finalen Code schreiben – er hat die Optionen recherchiert, das Team wählt gemeinsam den Ansatz.

Fazit

Einer der grössten Vorteile dieses Ansatzes ist die faire und offene Diskussion über jede neue Änderung oder Erweiterung des Systems. So wird verhindert, dass nur wenige Personen Entscheidungen monopolisieren, und alle Teammitglieder können sich am Entscheidungsprozess beteiligen. Ausserdem ermöglicht das Framework, erfahrene Ingenieure aktiv einzubinden.

Ermutigen Sie Ihre Teammitglieder, ihre Ideen zu teilen

Viele leitende Ingenieure haben das Gefühl, ihre Meinung zu wichtigen Designfragen würde ignoriert – oder sie äussern sie gar nicht. Dieses Framework schafft einen fairen Rahmen, in dem alle Ideen beitragen und diskutiert werden können.

Für Manager ist es auch ein wertvolles Werkzeug, um Beiträge zu bewerten. Ingenieure sollten ermutigt werden, Ideen klar zu kommunizieren – eine oft unterschätzte, aber essenzielle Fähigkeit. Konsistente Anwendung dieser Methode kann nicht nur bessere Designs fördern, sondern auch die fachliche und kommunikative Entwicklung Ihres Teams stärken.

Wenn Sie Hilfe benötigen, um Ihre Geschäftsziele schneller zu erreichen, kontaktieren Sie uns.