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

1. Ludewig, Lichter: Software Engineering
   
2. Mayr: Projekt Engineering
   
3. Starke: Effektive Software-Architekturen
   
4. Bien: Enterprise Architekturen
   
5. Siedersleben: Moderne Softwarearchitektur
   
6. Scrum
   
7. RUP und V-Modell [XT]
   
8. Stefan Zörner: Architekturen dokumentieren
   
9. Projektsteckbrief
   

Jochen Ludewig, Horst Lichter: Software Engineering

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: Projekt Engineering

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: Effektive Software-Architekturen

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.

Adam Bien: Enterprise Architekturen

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: Moderne Softwarearchitektur

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:

• Produktkonzept
• Product Backlog
• Sprint Backlog
• Sprint-Burndown-Bericht
• Sprint-Endbericht
• Verbesserungsmaßnahmen
• Hindernisliste
• Releaseplan
• Releasebericht

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).