Zur Dokumentation im Softwareentwicklungsprozess existieren sehr konträre Vorstellungen.
Überall (auch bei "leichtgewichtigen" "agilen" Prozessen) wird die Wichtigkeit bestimmter Dokumente betont.
Aber anders als in anderen Ingenieurwissenschaften gibt es in der Softwareentwicklung noch immer keinen Konsenz,
welche Dokumenttypen in welchem Unfang und in welcher Strukturierung mindestens notwendig
für ein erfolgreiches und langfristig wartbares Softwareprojekt sind.
Die verschiedenen Prozess- und Vorgehensmodelle zur Softwareentwicklung setzen unterschiedliche Schwerpunkte
und beschreiben teilweise über 100 zu erstellende Dokumenttypen (was durch "Tailoring" eingeschränkt werden kann).
In der Literatur zum Projekt Engineering, Software Engineering und zu Softwarearchitekturen wird mittlerweile meistens empfohlen,
die Dokumentation auf das wirklich notwendige zu beschränken,
aber es wird gleichzeitig betont, dass bestimmte Dokumente essenziell notwendig sind.
Im Folgenden werden einige Beschreibungen und Hinweise auf als wichtig angesehene Dokumentationen aufgeführt.
Inhalt
- Ludewig, Lichter: Software Engineering
- Mayr: Projekt Engineering
- Starke: Effektive Software-Architekturen
- Bien: Enterprise Architekturen
- Siedersleben: Moderne Softwarearchitektur
- Scrum
- RUP und V-Modell [XT]
- Stefan Zörner: Architekturen dokumentieren
- Projektsteckbrief
Jochen Ludewig und Horst Lichter stellen in ihrem
Buch
folgende Forderungen auf:
- Dokumentation ist wichtig für gute Softwarequalität und Wartbarkeit und muss hoch bewertet und anerkannt werden.
- Dokumentieren muss als Daueraufgabe begriffen werden und darf nicht erst am Ende der Kodierung erfolgen.
- Die Anforderungen an die Dokumente und die Verantwortlichkeiten müssen klar sein.
- Ablageort und die Strukturierung der Dokumente müssen definiert und einheitlich sein.
- Die Dokumente müssen geprüft und einer Konfigurationsverwaltung unterstellt werden.
Die Dokumenttypen werden in vier Taxonomie-Kategorien eingeteilt:
- Prozessdokumentation
Dokumente zum Entwicklungsprozess, beispielsweise:
Richtlinien, Handlungsanweisungen, Standards und Musterdokumente
- Projektdokumentation
Planung und Leitung des Entwicklungsprojekts, beispielsweise:
Projektauftrag, Projektplan, Projektstatusberichte, Projektabschlussbericht
- Systemdokumentation
Für die Konstruktion und Wartung benötigte Dokumente, beispielsweise:
Begriffslexikon, Anforderungsspezifikation, Spezifikation der Systemtestfälle, Abnahmespezifikation, Systemarchitektur und Programmcode
- Qualitätsdokumentation
Dokumente zur analytischen Qualitätssicherung, beispielsweise:
Audit-Protokolle, Test- und Review-Berichte, Abnahmebericht
Für bestimmte Dokumenttypen wird empfohlen, sich an Standards zu halten,
zum Beispiel die Norm IEEE Std 830 ("Recommended Practice for Software Requirements Specifications").
Zur Aufwandsabschätzung rechnen Ludewig und Lichter im Endergebnis mit einer Produktivität von 4 Seiten pro Tag.
Herwig Mayr nennt in seinem
Buch
folgende Ziele zur Dokumentation:
- Definiertes Dokumentenablagesystem mit Freigabe- und Verteilungsmechanismen sowie Konfigurations- und Versionsverwaltung
- Klare Definition, wer wann für wen welche Dokumente erstellt und pflegt
- Standards und einheitliche Strukturen der Dokumente
(das Projekthandbuch enthält Muster aller Dokumente)
- Verwendung einheitlicher Bezeichnungen
- Möglichkeit der Projektkontrolle anhand der Dokumentation
Laut Mayr ist die Anzahl der bei agilem Vorgehen produzierten Dokumente nicht wesentlich geringer als bei traditionellem Vorgehen.
Allerdings werden beim agilen Vorgehen viele Dokumente werkzeugunterstützt oder sogar automatisch generiert.
Mayr beschreibt folgende Dokumente bei traditionellem und beim agilen Vorgehen als essenziell (gekürzt):
-
Wichtiger bei traditionellem Vorgehen |
Wichtiger bei agilem Vorgehen |
Organigramm, Stellenbeschreibungen |
Projektbibliothek, Protokolle |
Konfigurationsmanagement |
Qualitätsmerkmale |
Zielbeschreibung |
Lastenheft |
Auftrag, Anforderungen |
Gesamtplan |
Grobplan, kurzfristige Feinpläne |
Benutzerdokumentation |
Risiko-Vorsorgeplan |
Fortschrittsberichte |
Zwischenprodukte, Prototypen |
Pflichtenheft |
Designmodell |
Quellcode |
Systemdokumentation |
(Anwendungs-)Daten |
Lauffähiges Programm |
Fehlerliste, Fehlerbericht |
Testplan, Testsuite |
Betriebsversion |
Installationsprotokoll, Inbetriebnahmeprotokoll |
Abnahmeprotokoll |
Abschlussbericht |
Wartungsplan, Pflegeplan |
|
Die Systemdokumentation umfasst folgende Komponenten:
- Systemstruktur
Modularisierung, Strukturen, Schnittstellen, Programmablaufplan, Aufrufhierarchie, Komponentenhierarchie
- Komponenten
Funktionenliste, zentrale Algorithmen, Datenmodell, Klassenbeschreibungen
- Externe Datenhaltung
Falls Verwendung externer Dateien, Daten, oder Datenbanken: Beschreibung
- Dynamisches Verhalten
Systemverhalten, Interaktionsmöglichkeiten, Ausgaben
- Installationsbeschreibung
Installationshandbuch, Fehlerbeschreibungen, Troubleshooting
- Begriffe
Lexikon
Gernot Starke geht (wie der Titel seines
Buches
auch nicht anders vermuten lässt) nur am Rande auf die Projektorganisation ein.
Aber bestimmte Dokumentationen betrachtet er als wichtige Aufgabe des Softwarearchitekten.
Typische Architekturdokumente sind:
- Übersichtspräsentation
Folienpräsentation (max. 1 h), fachliche und technische Architektur und Struktur des Systems
- Architekturüberblick
Funktionsweise des Systems, Architektur des Systems und die wesentlichen Strukturen, Begründung der wesentlichen Architekturentscheidungen, max. 30 Seiten
- Zentrale Architekturbeschreibung ("SWAD", Software-Architekturdokumentation)
Ausführliche Referenz, fachlicher Kontext,
sämtliche Architektursichten (Kontextsicht, Bausteinsicht, Laufzeitsicht, Verteilungs-/Infrastruktursicht, event. Datenmodellsicht),
Schnittstellendefinitionen, globale Entwurfsentscheidungen, Glossar
- Architekturtapete
Mischung aus Baustein- und Verteilungssicht
- Dokumentationsübersicht
Verzeichnis sämtlicher architekturrelevanter Dokumente
- Handbuch zur Architekturdokumentation
Richtlinien und Vorgaben, wie die Architekturdokumentation zu erstellen ist
- Technische Informationen zum Entwicklungsprozess
Die wichtigsten Informationen für Entwickler und Tester hinsichtlich Entwicklungsmethoden, Programmierung, Übersetzung/Bau und Start/Test des Systems
Unter
http://www.arc42.de
finden Sie downloadbare Templates hierzu.
Starke schätzt den Aufwand für die Ausgestaltung der Bausteinsicht am höchsten mit 60 bis 80 % der Zeit für die Architektursichten insgesamt.
Als wichtigstes Architekturergebnis definiert Adam Bien in seinem
Buch
zwei Dokumenttypen:
- MAD (Meta-Architekturdokument)
Erhöhung der Wartbarkeit durch Standardisierung:
Allgemeingültige Konzepte, Problemlösungen, Architektur, Framework, Probleme, Datenkonsistenz, Nebenläufigkeit,
Sperren, Verteilung, Schnittstellentypen, Patterns, Best Practices und Coding Conventions.
- PAD (Projektspezifisches Architekturdokument)
Vorgaben für das konkrete Projekt:
Abweichungen zum MAD, Vision, Stakeholder, Komponenten, Schnittstellen, Deployment,
Testkonzept, Betrieb, Monitoring, Errorhandling, Entwurfsentscheidungen und Glossar.
Johannes Siedersleben legt in seinem
Buch
besonderen Wert auf Schnittstellen und Komponenten.
Die erste Frage eines jeden Architektur-Revies lautet:
Aus welchen Komponenten besteht das System?
Die Antwort hierzu kann weder der Verweis auf ein Klassenmodell mit Tausenden von Klassen sein
noch der Verweis auf ein Schichtenmodell mit wenigen Ebenen.
Komponenten modularisieren das Gesamtsystem sinnvoll in überschaubare Einheiten, haben stabile und genau spezifizierte Schnittstellen
und sind einzeln testbar (eventuell auch einzeln versionierbar und austauschbar).
Bezüglich Softwarearchitektur-Dokumentation fordert Siedersleben ein für alle Projektmitglieder leicht verfügbares aktuelles Übersichtsbild zur Komponentenstruktur
und vollständig dokumentierte Schnittstellen und definierter Ausnahmebehandlung.
Ein wichtiges Qualitätsmerkmal einer guten Softwarearchitektur ist seine Komponentenstruktur mit großer Kohäsion innerhalb der Komponenten,
wenigen Abhängigkeiten zu anderen Komponenten und Zyklenfreiheit.
Scrum
Scrum gehört zu den
agilen
Vorgehensmodellen zum Softwareentwicklungsprozess.
Scrum benötigt vielleicht weniger Dokumentation als traditionelle RUP- und V-Modell-Vorgehensmodelle,
aber für einen agilen Prozess erstaunlich viel Dokumentation.
Roman Pichler beschreibt in seinem Buch
Scrum - Agiles Projektmanagement erfolgreich einsetzen
folgende Dokumentationen:
Boris Gloger beschreibt in seinem Buch
Scrum - Produkte zuverlässig und schnell entwickeln
folgende Ergebnis-Artefakte und Dokumentationen:
- Vision
- Product Backlog Item
- Product Backlog
- Sprint Goal
- Selected Product Backlog
- Aufgaben
- Sprint Backlog
- Releaseplan
- Impediment Backlog (Hindernisliste)
- Produkt-Inkrement
RUP und V-Modell XT
Einige wichtige beim RUP beziehungsweise beim V-Modell XT zu erstellende Dokumente sind unter
sw-dev-process.htm#RUP bzw.
sw-dev-process.htm#V-Modell
beschrieben.
Zum V-Modell XT finden Sie downloadbare Templates unter
http://www.v-modell-xt.de
(Datei "Produktvorlagen-Komplett.zip").
Stefan Zörner: Architekturen dokumentieren
Viele aktuelle Ideen zur Software- und Architekturdokumentation finden Sie bei Stefan Zörner:
Zusammenfassender Vortrag:
Kleines 1x1 der Architekturdokumentation.
Reihe bei jaxenter:
jaxenter 2008-09,
2008-10,
2008-12,
2009-01,
2009-02,
2009-04.
Stichworte für einen Projektsteckbrief
Insbesondere in der Startphase eines Softwareprojekts wird gerne ein "Steckbrief" zum Projekt erstellt.
Er soll vorab in einem einzigen Dokument wichtige Aspekte zusammenfassen, welche das Projekt charakterisieren.
Häufig sind auch zu berücksichtigende Rahmenbedingungen enthalten.
Im Folgenden sind mögliche Stichworte für einen Projektsteckbrief aufgelistet.
Sie können nur als Beispiel dienen und müssen für konkrete Projekte durch Passenderes ersetzt werden.
-
Fachliche Vision, Systemidee und Zielsetzung
- Was soll das Produkt können?
- Was ist das Besondere daran?
- Wer ist der Anwender bzw. die Zielgruppe?
- In welchem groben Zeitrahmen ist die Fertigstellung geplant?
-
Beteiligte, Stakeholder und Ressourcen
- Wer hat Interesse an dem Produkt?
- Wen könnte die Entwicklung oder das Produkt beeinträchtigen und wer könnte ein Gegner des Projekts sein?
- Wer ist der Geldgeber?
- Wer hat Einfluss auf die Prozesse und wer setzt die Rahmenbedingungen und fällt wichtige Entscheidungen?
- Welche fremden Ressourcen werden benötigt?
- Wer formuliert die fachlichen Anforderungen?
- Wer konzipiert die Softwarearchitektur, führt die technische Entwicklung durch und dokumentiert alles?
- Wer kümmert sich um die Entwicklungsinfrastruktur (Versionierung, SCM, Nexus, Jenkins, SonarQube, Testumgebungen, Continuous Integration, Profiling, Lasttest, Auslieferung, Deployment, Continuous Delivery, Betriebsübergabe, Wiki etc.)?
- Wer erstellt automatisierte per Jenkins ausgeführte Integrationstests und Akzeptanztests?
- Wer macht Qualitätssicherung und Abnahme?
- Scrum oder Kanban?
- Falls Scrum: Wer ist Product Owner und wer ScrumMaster?
-
Schnittstellen und Abhängigkeiten
- Fachliche Schnittstellen zu anderen Systemen, anderen Abteilungen und externen Partnern.
- Technische Schnittstellen zu anderen Systemen.
- Versionierungs- und Deployment-Abhängigkeiten.
-
Technische Rahmenbedingungen und grundsätzliche technische Designentscheidungen
- Relationale Datenbank oder NoSQL-Datenbank?
- Java EE Application Server oder TomEE oder Spring Boot oder OSGi enRoute Web Server Extender?
- EJB? ROA? RAML? Microservices mit REST? µservices mit OSGi?
- Resilience mit Hystrix und Spring Cloud?
- Falls Web-GUI: JSF oder GWT oder AngularJS?
- XML/XSD oder JSON?
- Quartz Scheduler oder Java-EE-Batch?
- Test per CDI-Unit oder OpenEJB oder Arquillian?
- Maven oder Gradle?
- Mercurial oder Git?
- Continuous Delivery?
- Docker?
- Private Cloud, Public Cloud, SaaS, PaaS, IaaS?
- Monitoring? Auditing?
-
Technisches Grobkonzept
- Übersichtsdiagramm.
- Kontextabgrenzungsdiagramm.
- Grobe Systemaufteilung.
- Struktur- und Bausteinsicht.
- Verteilungssicht, Datenmodellsicht, Mengengerüste.
- Schnittstellendesign.
- Workflows, Monitoring, Reporting.
- Aktivitätsdiagramme.
- Sicherheit, Entkopplung, Skalierbarkeit, Cluster-Fähigkeit, kein Single Point of Failure (SPOF), Wiederanlauffähigkeit, Backup, Failover etc.
- Wichtige Patterns (z.B. Pipes-und-Filter-Pattern).
- Coding Conventions (nicht nur Java, sondern auch DB und Konfiguration).
Weitere Themen: andere TechDocs
| Softwarearchitekt
| Prozess- und Vorgehensmodelle zur Softwareentwicklung
© 2009 Torsten Horn, Aachen