Dokumente mit technischen Anforderungen schreiben - ERDs

Was ist ein ERD?

Bei FloQast haben wir einen ständigen Arbeits- und Ideenstau, der vom Produktteam zum Engineering-Team fließt. Häufig werden uns diese Ideen für neue Funktionen in Form einer präsentiert PRD (Produktanforderungsdokument) und oft ist es für uns als Ingenieure von entscheidender Bedeutung, diese Ideen in unsere Version eines ERD (Engineering Requirement Document, auch bekannt als Technical Requirement Document) umzusetzen. Ein ERD dient als Blaupause dafür, wie das Engineering-Team plant, das ihnen gestellte Problem zu lösen. Es bietet unseren Ingenieuren, die an der Funktion oder dem Produkt arbeiten, die Möglichkeit, die Anforderungen zu verdauen, bevor sie Code schreiben. Es verschafft den Ingenieuren nicht nur ein besseres Verständnis des Problems, sondern gibt den Ingenieuren auch Zeit, um zu versuchen, das vorgeschlagene Produkt und seine Lösung zu untersuchen.

Was sollte ein ERD enthalten?

Bei unseren ERDs gibt es keine strenge Regel, was sie enthalten sollten, aber zumindest sollte sie eine grobe Übersetzung der Produktspezifikationen in technische Spezifikationen enthalten. Oft beinhaltet das Ideen für neue Schemas oder Änderungen an bestehenden Schemas sowie Architekturdiagramme, die Code, Infrastruktur und Tools darstellen. Das Dokument sollte gründlich, aber nicht übermäßig sein. Wir schaffen einen umfassenden Überblick über das, was kommen wird, aber wie jeder gute Plan sollte er flexibel und flüssig bleiben. Vor diesem Hintergrund ist es oft Sache der Person, die am ERD arbeitet, zu entscheiden, was darin am hilfreichsten wäre, damit es als Guide für ihr Team dienen kann. Im Allgemeinen habe ich Erfolg damit gehabt, dass meine ERDs die folgenden Themen enthalten:

• MVP-Funktionalität: Dies steht in der Regel an oberster Stelle des ERD und enthält eine Zusammenfassung dessen, was dieser EED zu produzieren beabsichtigt.
• Architektur: In diesem Abschnitt enthalte ich normalerweise bis zu drei Abschnitte für Bestehende, Zukunft, und Nahe Zukunft Architektur. Die Verwendung dieser Abschnitte hängt davon ab, welche Architektur möglicherweise bereits existiert und ob der MVP/PRD eine inkrementelle Lösung erfordert oder nicht. In diesem Abschnitt verwende ich am häufigsten Diagramme, um detailliert zu beschreiben, wie die verschiedenen Bereiche unserer Codebasis und Infrastruktur zusammenarbeiten werden.

• Bereiche, die Anlass zur Sorge geben: Ich verwende diesen Abschnitt, um alle wichtigen Bedenken, die wir während der ERD-Recherche und -Erstellung festgestellt haben, detailliert darzustellen. Die Themen in diesem Abschnitt werden sich in heftigen, zeitlich begrenzten Nutzerberichten niederschlagen, mit denen alle erheblichen Zweifel an möglichen Lösungen geklärt werden. Anstatt diese Zweifel mit in den Entwicklungsprozess zu nehmen, werden diese Spitzen wie jedes andere Problem während des Sprints bearbeitet, aber die Lösungen werden genutzt, um neue Probleme mit klar definierten Zielen zu schaffen.
• Schemata: Es ist immer wichtig, einen detaillierten Überblick über die Daten zu haben, mit denen wir für das Projekt arbeiten werden, sodass es einen eigenen Abschnitt innerhalb des ERD rechtfertigt.
• Umsetzung/Karte von PRD zu ERD: Schließlich, nachdem das ERD gefestigt ist und wir beginnen, es in Tickets aufzuteilen, füge ich einen Abschnitt PRD zu ERD hinzu. Hier verknüpfen wir die Tickets, die wir erstellt haben, mit bestimmten Themen innerhalb der PRD. Vor diesem Hintergrund können wir schnell erkennen, wie verschiedene Teile des ERD dem spezifischen Geschäftswert entsprechen, der in der PRD beschrieben wurde.

Wo soll ich mit der ERD-Erstellung beginnen

Oft ist der schwierigste Teil einer ERD der erste Start. Es gibt wahrscheinlich eine Menge Informationen, die wir in der PRD zu übersetzen versuchen, und wenn wir den besten Ausgangspunkt finden, wird das Schreiben der ERD einfacher. Im Allgemeinen betrachte ich das Problem beim Schreiben einer ERD zunächst von Grund auf. Ein fundiertes Verständnis der Daten, mit denen ich arbeiten werde, hilft mir bei meinen weiteren Entscheidungen. Mit den Daten und ihrer Struktur im Hinterkopf kann ich beginnen, die verschiedenen Dienste oder Funktionen zu visualisieren, die zusammenarbeiten müssen, um unsere Architektur zu formalisieren oder bestehende zu untersuchen. Von dort aus habe ich in der Regel eine Grundlage, die es mir ermöglicht, zu verstehen, wie die Funktionen unseres Produkts in unsere Architektur passen. Zu diesem Zeitpunkt hätte ich höchstwahrscheinlich mehrere Fragen an das Produktteam gestellt, da ich technisch schwierige Bereiche im Code, funktionale Randfälle oder einfach nur um Klarheit darüber zu suchen, wie eine Funktion funktionieren sollte. Dieses Muster hat sich für mich bewährt, unabhängig davon, ob ich ein Projekt ohne vorhandenen Code/Daten starte oder mit etwas anderem, das bereits vorhanden ist. Danach kann ich feststellen, dass der technische Plan etwas grandios erscheint. Die neuen Tools, Codebasen, Schema-Migrationen usw., von denen ich entschieden habe, dass sie für das Projekt notwendig sind, könnten die Zeit verdoppeln, die ich ursprünglich für nötig gehalten hatte. Dies ist der perfekte Zeitpunkt dafür. Nachdem wir unseren ERD-Entwurf in der Hand haben, können wir unsere Ergebnisse unserem Produktteam zusammen mit einer groben Schätzung vorlegen, um die Arbeiten abzuschließen. Von dort aus stellen wir in der Regel fest, dass wir mit dem Produktteam zusammenarbeiten können, um dem Projekt etwas Fett abzubauen und ein schlankeres MVP zu erstellen, was sich auch auf unser ERD auswirken sollte. Wenn das Projekt bereits so schlank wie möglich ist, müssen wir uns vielleicht mit der Erstellung von Phasen für unsere Implementierung befassen und dies im ERD dokumentieren. Am Ende sollte das ERD am besten darstellen, wie unser Team versucht, das ihnen vorgelegte Problem auf eine Weise zu lösen, die auch unserem Produktteam demonstriert werden kann.

Letzte Gedanken

Schließlich haben wir keine Angst davor, unsere ERD als lebendes Dokument zu behandeln. Da der Umfang der Funktion, an der wir gerade arbeiten, zunimmt oder abnimmt, kann es hilfreich sein, unseren ERD weiter zu überarbeiten. Dieses lebendige Dokument hilft dabei, den Überblick darüber zu behalten, was geplant und was implementiert wurde. Es dient als Einführung für Teammitglieder, die in der Mitte des Projekts beginnen, und schließlich, wenn alles gesagt und getan ist, als Katalysator für Diskussionen während einer Projektrückschau dienen. Ein gut ausgearbeitetes ERD steht für die harte Arbeit und Zeit, die das Engineering-Team aufgewendet hat, um vollständig zu verstehen, was es erstellen soll und wie sich das auf seine Codebasis auswirken könnte. Ohne einen richtigen Plan ist es allzu leicht, Ihrem Team dabei zuzusehen, wie es mit dem Umfang rutscht, wenn es neue technische Probleme entdeckt oder nicht versteht, wie ein Feature voraussichtlich architektonisch behandelt wird. Ich hoffe, dieser Artikel hat Ihnen einen guten Einblick in die Planung unserer Entwicklung bei FloqAst gegeben und eine Idee, wie Sie Ihr eigenes ERD schreiben können.