Leitfaden: Dokumentation und Spezifikation von Softwaredesigns

Was ist eine Softwaredesignspezifikation?

Eine Softwaredesignspezifikation oder ein Softwaredesigndokument (SDD) ist ein umfassendes Dokument, das die Architektur, die Komponenten, die Schnittstellen und andere wichtige Elemente eines Softwareentwicklungsprojekts beschreibt.

Im Kern ist eine Softwaredokumentation ein Entwurf, der Entwickler, Designer und Stakeholder durch den Softwareentwicklungsprozess führt. Er enthält detaillierte Beschreibungen der Systemfunktionen, Datenstrukturen, Algorithmen und Benutzeroberflächen. Durch die vorherige Definition dieser Elemente trägt das Softwaredesigndokument dazu bei, dass alle Teammitglieder die Ziele und Anforderungen des Projekts verstehen. Diese Klarheit ist für die Aufrechterhaltung der Konsistenz und Qualität während des gesamten DevOps-Lebenszyklus unerlässlich, da sie die Wahrscheinlichkeit von Fehlkommunikation und Designfehlern verringert.

Warum sind Softwaredesignspezifikationen wichtig?

Die Bedeutung von Softwaredesignspezifikationen kann nicht hoch genug eingeschätzt werden. In erster Linie dienen sie als Vertrag zwischen Stakeholdern und Entwicklern und stellen sicher, dass alle Parteien auf die erwarteten Ergebnisse ausgerichtet sind. Diese Ausrichtung minimiert das Risiko von Scope Creep, also die Überschreitung des ursprünglich vereinbarten Projektumfangs, und hilft, das Projekt auf Kurs und im Budget zu halten. Darüber hinaus bietet ein Softwaredesigndokument einen Bezugspunkt, der für zukünftige Iterationen, Wartungsarbeiten und Upgrades verwendet werden kann und effizientere Änderungen ermöglicht.

Eine gut dokumentierte Designspezifikation ermöglicht es Teams außerdem, neue Mitglieder schneller zu integrieren, da das Dokument als umfassender Leitfaden für die Architektur und Funktionalität des Systems dient. Letztendlich zahlt sich die Investition in ein hochwertiges Softwaredesigndokument aus, indem es eine bessere Zusammenarbeit fördert, die Codequalität verbessert und den Gesamterfolg des Softwareprojekts steigert.

Auch wenn das Inhaltsverzeichnis von Softwaredesigndokumenten in der Technologiebranche unterschiedlich sein kann, bleiben die Vorteile gleich:

• Es dient als Single Source of Truth. Das Softwaredesigndokument definiert die Projektziele, den Umfang sowie die geschäftlichen und technischen Anforderungen im Detail und enthält zugehörige Informationen, um Missverständnisse zwischen dem Entwicklungsteam, dem Produktmanagement und den leitenden Stakeholdern zu vermeiden.
• Vermeidung von schleichender Erweiterung des Projektumfangs. Softwaredesigndokumente unterstützen Projektmanager bei der genauen Schätzung der für das Projekt erforderlichen Ressourcen, Zeit und des Budgets, indem sie das detaillierte Design und die technischen Anforderungen beschreiben. Projektteams können auch detaillierte Softwaredesigndokumente verwenden, um eine schleichende Erweiterung des Projektumfangs zu vermeiden und potenzielle Risiken und Strategien zur Risikominderung frühzeitig zu erkennen.
• Erleichtert die Zusammenarbeit. Die Veröffentlichung des Softwaredesigndokuments in einem Collaboration Tool, wie zum Beispiel ein Notion-Wiki oder ein Confluence-Bereich, erleichtert die Teamarbeit und Koordination, insbesondere in funktionsübergreifenden Teams. Jeder Entwickler kennt seine Rolle und Verantwortlichkeiten, wodurch Überschneidungen reduziert werden und sichergestellt wird, dass alle Komponenten harmonisch entwickelt werden. Dies ist besonders in agilen Umgebungen wichtig, in denen iterative Entwicklung und kontinuierliche Integration eine effiziente Teamkoordination erfordern.
• Fördert die Qualität. Das Designdokument ist ein Qualitätsmaßstab für das Entwicklungsprojekt, da es sicherstellt, dass das Endprodukt dem erforderlichen Design und der erforderlichen Funktionalität entspricht. Es legt auch die Erfolgskriterien und Standards für Codierungspraktiken, Testverfahren und Dokumentation fest.

Wie man eine Softwaredesignspezifikation schreibt

Das Schreiben eines Softwaredesigndokuments erfordert einige Vorbereitungen, da das Dokument das Fachwissen und den Input eines funktionsübergreifenden Teams benötigt, dessen Mitglieder andere Aufgaben haben als nur das Schreiben von Designdokumenten.

Ein typisches Team für die Erstellung von Designspezifikationen umfasst:

• Entwickler
• Unternehmens-, Cloud- und Lösungsarchitekten
• Tester
• Geschäftsanalysten
• UI- und UX-Designer
• Technische Redakteure

Sobald das funktionsübergreifende Team zusammengestellt ist, muss es mehrere wichtige Vorbereitungsschritte unternehmen, um eine erfolgreiche Dokumententwicklung sicherzustellen:

1. Definition der Rollen und Verantwortlichkeiten. Es ist wichtig, die Rollen und Verantwortlichkeiten klar zu definieren, um die Dokumententwicklung zu optimieren. Berücksichtigen Sie die Verfügbarkeit von leitenden Entwicklern und Architekten für die Schreibaufgaben. Bieten Sie diesen Entwicklern Unterstützung bei der technischen Dokumentation an und konzentrieren Sie sie besonders auf Abschnitte, in denen ihr Fachwissen am meisten von Nutzen ist.
2. Erfassen der Anforderungen. Das Schreiben eines Softwaredesigndokuments beginnt mit Interviews, um die Anforderungen und Erwartungen der Stakeholder zu erfassen. Zu diesem Zeitpunkt werden zunächst vorhandene Anforderungsdokumente, User Stories und zugehörige Dokumentationen gesammelt und vom Team geprüft.
3. Systemintegrationen abbilden. Ein weiterer wichtiger Vorbereitungsschritt ist die Erstellung von Diagrammen, um die Systemumgebung und die Interaktionen mit anderen Bereichen, wie zum Beispiel anderen Backend-Systemen in der Organisation, zu skizzieren. Das Dokument sollte auch erfassen, wie das System mit Partner- oder Lieferantensystemen, wie zum Beispiel externen Zahlungsabwicklern, interagiert. Nehmen Sie sich die Zeit, Anwendungsfälle zu entwickeln, die funktionale Anforderungen erfassen und vermitteln, wie verschiedene Systemteile interagieren.
4. Definition von Projektziel und -umfang. Definieren Sie klare Ziele und einen klaren Umfang für das Projekt, um die Ausrichtung auf die Geschäftsziele der Organisation sicherzustellen. Jetzt ist es an der Zeit, die Stakeholder des Unternehmens oder ihre Beauftragten in die Diskussion einzubeziehen. Laden Sie sie zu einem Zoom-Anruf ein oder, noch besser, in den gleichen Raum wie das Projektteam, damit sie zusammenarbeiten, diskutieren und sich gegenseitig Fragen stellen können.

Inhalt eines Softwaredesigndokuments

Es gibt mehr als eine Möglichkeit, eine Vorlage für ein Softwaredesigndokument zu erstellen. Letztendlich muss der Verfasser mit Entwicklungsteams und beteiligten Akteuren zusammenarbeiten, um einen Standard für Softwaredesigndokumente für die Organisation festzulegen. Einige Standards, wie zum Beispiel IEEE 1016-2009, regeln den Informationsgehalt eines Softwaredesigndokuments. Viele Organisationen arbeiten jedoch mit einem angepassten Softwaredesigndokument, das ihren Bedürfnissen entspricht.

Hier sind einige gemeinsame Elemente eines Softwaredesigndokuments als Referenz.

1. Titelseite

Die Titelseite eines Softwaredesigndokuments enthält:

• Projekttitel
• Projektinhaber
• Autoren
• Mitglieder des Entwicklungsteams
• Versionsverlauf

In der Regel enthält die Titelseite eines Softwaredesigndokuments auch eine Versionstabelle, die die Versionierung und die Änderungen dokumentiert, die das Dokument durchläuft. Eine Überprüfungstabelle mag zwar wie ein Relikt der Vergangenheit erscheinen, aber Compliance-Prüfer suchen im Rahmen ihrer Prüfungen nach diesen Informationen.

2. Einleitung

Die Einleitung eines Softwaredesigndokuments enthält eine kurze Zusammenfassung des Projekts in fünf bis zehn Sätzen. Sie enthält auch ein Glossar der im Softwaredesigndokument verwendeten Begriffe und eine Auflistung der Projektziele. Berücksichtigen Sie beim Verfassen einer Einleitung auch Zielgruppen, die keine Entwickler sind, wie zum Beispiel das Führungsteam, das möglicherweise eine kurze Einführung in das Projekt benötigt.

3. Aktuelles Design

Hier fügt das Team das aktuelle Design der Anwendung ein. Das Team kann die Dokumentation einer Anwendung rückentwickeln, zum Beispiel durch das Schreiben eines Softwaredesigndokuments für eine Anwendung, die bereits in Produktion ist und für die keine oder eine stark veraltete Dokumentation vorhanden ist. Es gibt auch Fälle, in denen die Dokumentation des aktuellen Designs hilfreich ist, zum Beispiel bei der Migration einer älteren lokalen Anwendung zu Cloud-Diensten.

4. Vorgeschlagenes Design

Der Abschnitt vorgeschlagenes Design eines Softwaredesigndokuments enthält eine detaillierte Beschreibung der Architektur, Funktionalität und Komponenten des neuen Systems.

Dies ist in der Regel einer der umfangreichsten Abschnitte eines Softwaredesigndokuments, da er die Designmuster und -prinzipien für die Implementierung der Software umreißt. Dieser Abschnitt enthält auch Diagramme und Modelle, um die Systemstruktur und den Datenfluss visuell darzustellen. Darüber hinaus wird erläutert, wie das vorgeschlagene Design die Projektanforderungen erfüllt und wie identifizierte Probleme angegangen werden. Schließlich werden die ausgewählten Technologien und Tools und die Gründe für deren Einsatz erörtert.

5. Geplante Änderungen

Fügen Sie eine detaillierte Liste der geplanten Änderungen für das Projekt bei. Solche Änderungen lassen sich am besten in einer Tabelle kommunizieren, die Folgendes enthält:

• Überblick über die Änderungen, einschließlich des Zwecks der Änderungen und ihrer erwarteten Auswirkungen.
• Detaillierte Beschreibung, einschließlich des Ist-Zustands, des Soll-Zustands und der Begründung.

Der Umfang der Änderungen beschreibt, welche Anwendungskomponenten von Abhängigkeiten zwischen den geplanten Änderungen und anderen Systemkomponenten oder externen Systemen betroffen sind.

6. Testplan

Der Abschnitt Testplan des Softwaredesigndokuments sollte einen Link zum Testplan des Projekts enthalten. Während es früher üblich war, einen vollständigen Testplan beizufügen, ist es im Zeitalter von Online-Dokumenten einfacher, einfach auf den Testplan zu verlinken.

7. Überwachungsplan

Dieser Abschnitt enthält einen detaillierten Überwachungsplan, einschließlich relevanter Metriken, sobald die Anwendung während der Pilotphase Datenverkehr von Benutzern erhält.

8. Bereitstellungsplan

Der Abschnitt Bereitstellungsplan enthält einen detaillierten Plan und Rahmen für die Bereitstellung der Anwendung. Der Bereitstellungsplan ist einer der größten Abschnitte eines Softwaredesigndokuments und deckt mehrere Aspekte der Softwarebereitstellung ab:

• Einführung, einschließlich eines kurzen Überblicks über den Bereitstellungsplan, die Bereitstellungsziele und die wichtigsten Stakeholder.
• Bereitstellungsstrategie, einschließlich Bereitstellungsansatz und Begründung der Strategie.
• Voraussetzungen vor der Bereitstellung, einschließlich System- und Umgebungsvoraussetzungen, Konfigurationseinstellungen und Datenmigrationsanforderungen sowie Sicherheits- und Compliance-Prüfungen.
• Bereitstellungsphasen, die detaillierte Schritte für jede Phase der Bereitstellung, den Zeitplan, die Meilensteine und die Verantwortlichkeiten der Teammitglieder enthalten.
• Bereitstellungsumgebung, insbesondere die Zielumgebung(en).
• Schritte zur Einrichtung und Konfiguration der Umgebung.
• Verifizierungs- und Validierungsverfahren.
• Tools und Ressourcen, einschließlich einer Liste der für die Bereitstellung und Ressourcenzuweisung erforderlichen Tools.
• Bereitstellungstests, einschließlich Testverfahren vor der Bereitstellung, Kriterien für eine erfolgreiche Bereitstellung und Validierungsschritte nach der Bereitstellung.
• Risikomanagement, einschließlich der Identifizierung potenzieller Risiken, Minderungsstrategien und Notfallpläne.

9. Kommunikationsplan

Der Abschnitt Kommunikationsplan eines Softwaredesigndokuments beschreibt die Kommunikationsstrategie für die Stakeholder und legt fest, wie und wann die Stakeholder über den Projektfortschritt und wichtige Entscheidungen informiert werden sollen. Er legt den Bereitstellungszeitplan und die Benachrichtigungen fest und stellt sicher, dass alle relevanten Parteien die Zeitpläne und mögliche Systemausfallzeiten kennen.

In diesem Abschnitt wird auch der Berichterstattungsprozess beschrieben, einschließlich der Häufigkeit und des Formats der Fortschrittsberichte, um alle auf dem Laufenden zu halten. Darüber hinaus wird der Dokumentationsprozess detailliert beschrieben und hervorgehoben, welche Dokumente während des gesamten Projektlebenszyklus erstellt, gepflegt und weitergegeben werden. Der Plan stellt sicher, dass die Kommunikationskanäle klar definiert und für alle Beteiligten zugänglich sind. Schließlich enthält er einen Feedback-Mechanismus, um die Anliegen der Beteiligten effektiv zu erfassen und zu berücksichtigen.

10. Dokumentationsplan

Es ist wichtig, die technische Dokumentation als Teil des Produkts zu betrachten. Fügen Sie daher einen Abschnitt über die technische Dokumentation hinzu, die mit dem Produkt ausgeliefert wird. Beschreiben Sie die Strategie und die Schritte zur Erstellung von Online-Hilfe und Benutzerunterstützung.

11. Rollback-Plan

Das Zurücksetzen auf eine frühere Version der Anwendung erfordert Planung und Koordination, vor allem, wenn die Anwendung externen, zahlenden Kunden dient. Fügen Sie dem Softwaredesigndokument einen detaillierten Plan bei, der den Rollback-Plan für das Projekt Schritt für Schritt darstellt.

12. Projektauswirkungen

Der Abschnitt Projektauswirkungen des Softwaredesigndokuments sollte sich auf Kostenanalyse, Sicherheitsanalyse, Auswirkungen auf andere Geschäftsbereiche und Risikoanalyse konzentrieren.

13. Bewertungskriterien

Der Abschnitt mit den Bewertungskriterien sollte spezifische Metriken und Benchmarks zur Messung der Leistung und Effektivität des Systems enthalten. Er sollte die Testverfahren und Erfolgskriterien für funktionale und nichtfunktionale Anforderungen wie Benutzerfreundlichkeit, Zuverlässigkeit und Skalierbarkeit darlegen. Darüber hinaus sollte dieser Abschnitt die Methoden zur Erfassung und Analyse von Benutzer-Feedback spezifizieren, um sicherzustellen, dass das Design den Bedürfnissen und Erwartungen der Stakeholder entspricht.

14. Arbeitszeitplan

In den Softwaredesigndokumenten sollte auch der Arbeitszeitplan für das Projekt angegeben werden. Wenn Sie das Softwaredesigndokument in einem Collaboration Tools wie einem Confluence-Bereich oder ein Notion-Wiki veröffentlichen, suchen Sie nach Möglichkeiten, es mit dem Projektzeitplan in der Projektmanagementanwendung zu verknüpfen oder den Zeitplan in das Softwaredesigndokument einzubetten.

15. Verwendete Quellen

In diesem Abschnitt werden alle Ressourcen von Drittanbietern erfasst und dokumentiert, die zu den Phasen der Dokumenterstellung beigetragen haben. Einige Standardreferenzen, die Sie einbeziehen sollten, sind die folgenden:

• Interne Dokumente, wie zum Beispiel Anforderungsdokumente und ähnliche Dokumente.
• Analyseberichte, die während der Erstellung des Softwaredesigndokuments herangezogen wurden.
• Interne Strategiedokumente und Präsentationsfolien.

Beispiele für Softwaredesignspezifikationen

Es ist üblich, Vorlagen und Dokumente von früheren Arbeitgebern und Verträgen in der IT-Branche aufzubewahren. Betrachten Sie sie als Vorlagen, die Sie selbst mitbringen. Vorlagen und Templates für Softwaredesigndokumente unterscheiden sich von Unternehmen zu Unternehmen aufgrund der Bedürfnisse von Kunden, Stakeholdern, Geschäftsverträgen und anderen damit zusammenhängenden Angelegenheiten.

Es ist nichts Falsches daran, mit einer extern beschafften Vorlage zu arbeiten, wenn die Verfasser sie als Ausgangspunkt betrachten und sich dennoch von ihren Teams und Stakeholdern Feedback darüber einholen, was sie in einem Standard-Format für ein Softwaredesigndokument benötigen. Verwenden Sie diese Vorlagen als Leitfaden für den Dokumententwicklungsprozess.

Die Vorlage Design & System Requirements Template ist in der Notion-Bibliothek verfügbar. Sie wurde von Odette Jansen erstellt.

Nuclino ist ein SaaS-Workspace-Produkt, das ebenfalls eine Produktspezifikationsvorlage enthält.

Tipps für das Verfassen eines guten Softwaredesigndokuments

Das Verfassen eines Softwaredesigndokuments ist oft eine Teamarbeit, bei der das Fachwissen und die Talente eines Teams zusammengeführt werden. Nicht jeder ist von Beruf aus ein Autor.

Content Management

Ein wichtiger Teil beim Verfassen eines Softwaredesigndokuments ist die Verwaltung und Organisation des Autorenteams entsprechend dem Fachwissen der Teammitglieder.

• Erwartungen sollten so festgelegt werden, dass nicht jeder im Team an der gesamten Softwaredokumentation arbeiten muss, und die Aufgaben entsprechend verteilt werden.
• Ernennen Sie einen Dokumentenverantwortlichen, der ein Business Analyst, technischer Redakteur oder technischer Leiter sein kann, um das Schreiben und Bearbeiten der Softwaredokumente zu koordinieren.
• Beauftragen Sie ein Kernteam für das Projekt von der Idee bis zur Fertigstellung, das über genügend technisches Wissen verfügt, um die Inhalte verschiedener Autoren zu einem einheitlichen Stil zusammenzuführen.
• Vermeiden Sie es, Entwickler oder technisches Personal an einen Unternehmens-Styleguide zu binden, um ihren Schreibstil zu diktieren. Sorgen Sie stattdessen für ihren Erfolg, indem Sie sie ermutigen, einfach und prägnant zu schreiben.
• Arbeiten Sie mit Teammitgliedern zusammen, die sich mit dem Schreiben nicht wohlfühlen, und mit jemandem, der sich damit auskennt. Technische Redakteure oder Lektoren können ihnen während der Schreibphase umsetzbares Feedback geben.

Bearbeitung eines Softwaredesigndokuments

Aufgrund der kurzen Fristen und funktionsübergreifenden Teams ist es wichtig, bei der Bearbeitung einer Softwaredokumentation detailliert vorzugehen. Konzentrieren Sie sich bei der Bearbeitung eines Softwaredesigndokuments auf das Fachwissen des Teams. Bitten Sie beispielsweise keine Architekten oder Entwickler, die Grammatik zu überprüfen, da das Ergebnis möglicherweise ein Softwaredesigndokument mit mehr Grammatikfehlern als das Originaldokument ist. Definieren Sie die Bearbeitungsrollen auf der Grundlage der Stärken der Teammitglieder, wie zum Beispiel:

• Entwicklungsredaktion. Dies ist ideal für Stakeholder, die Fragen zum Entwurf stellen möchten. Sie können sich auf den Inhalt konzentrieren und konstruktives Feedback zur Ausrichtung des Softwaredesigndokuments geben.
• Technische Überprüfung. Ingenieure und Architekten überprüfen die Softwaredokumentation auf technische Genauigkeit und Durchführbarkeit.
• Inhaltsredaktion. Der technische Redakteur überprüft den Inhalt auf Grammatik, Fluss, Konsistenz und Wirkung. In der Regel werfen ihre Änderungen Fragen für die Analysten, Ingenieure und Architekten des Teams auf.

Da Softwaredesigndokumente von mehreren Autoren verfasst werden, ist es wichtig, die während der Bearbeitungsphase vorgenommenen Änderungen und Kommentare nachzuverfolgen. Wenn das Team für die Bearbeitung in Microsoft 365 arbeitet, verwenden Sie die Funktion Änderungen nachverfolgen in Microsoft Word. Verwenden Sie ebenso die Funktion Änderungen vorschlagen und Kommentar hinzufügen in Google Docs, wenn die Organisation Google Workspace verwendet.

Verfassen eines Softwaredesigndokuments

Ein komplexes und schlecht geschriebenes Softwaredesigndokument ist im Projektmanagement keine Seltenheit. Selbst wenn dem Projekt ein technischer Redakteur zugewiesen ist, sollten Sie die folgenden grundlegenden Tipps befolgen:

• Schreiben Sie in kurzen Sätzen und Absätzen, um die Lesbarkeit zu verbessern.
• Verwenden Sie großzügig Beispiele, insbesondere Stücklisten und Diagramme, wo dies angebracht ist.
• Implementieren Sie einen KI-Schreibassistenten, um Autoren zu unterstützen.
• Verwenden Sie großzügig Überschriftenstile, um das Dokument leichter lesbar zu machen.

Die Verwendung generativer KI zum Verfassen von Designdokumenten kann riskant sein, insbesondere wenn die Organisation keine allgemeine Richtlinie zur Nutzung von KI hat. Alle Daten, die Teammitglieder in öffentliche generative KI-Tools wie ChatGPT eingeben, könnten für Trainingsdaten verwendet werden, was bedeutet, dass ihre Inhalte möglicherweise öffentlich zugänglich sind.

Einfügen von grafischen Elementen

Die Verwendung von visuellen Elementen in Softwaredesigndokumenten verbessert die Lesbarkeit. Visualisierungs-Tools haben sich seit Microsoft Visio auf dem Desktop stark weiterentwickelt. Ziehen Sie daher andere Optionen in Betracht, wie zum Beispiel das Einbetten von Miro-Diagrammen in das Dokument. Miro ist eine Plattform für Teamzusammenarbeit und Projektmanagement.

Hier sind einige visuelle Elemente, die für die Softwaredokumentation in Betracht gezogen werden sollten:

• Cloud-Architekturdiagramme
• Netzwerkdiagramme
• Zeitleisten

Feedback einholen

Das Einholen von Feedback sollte ein kontinuierlicher Prozess sein, keine einmalige Überprüfung. Das Team und die internen Stakeholder sollten zu jeder wichtigen Version des Dokuments einen Beitrag leisten.

Regelmäßige Aktualisierung des Dokuments

Die Entwicklung des Designdokuments für eine komplexe Cloud-native-Anwendung erfordert Zeit und Fachwissen, die Teams durch die Implementierung von Prozessen und Gates wiedererlangen können, um sicherzustellen, dass die Entwicklungsteams ihre Softwaredesigndokumente im Rahmen des Projektlebenszyklus aktualisieren.