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.
Jochen Ludewig und Horst Lichter stellen in ihrem Buch folgende Forderungen auf:
Die Dokumenttypen werden in vier Taxonomie-Kategorien eingeteilt:
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:
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 |
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.
Die Systemdokumentation umfasst folgende Komponenten:
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:
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:
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 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:
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").
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.