Warum lohnt es sich zu dokumentieren? Was spricht dafür?
| Begründung | Dokumentationsstufe |
|---|---|
| Wissen/Erfahrungen sichern (Team-mitglieder nicht mehr verfügbar) | 1 |
| Nachvollziehbarkeit von (Design-) Entscheidungen ermöglichen | 1 |
| Nicht-funktionale Anforderungen festhalten und berücksichtigen | 1 |
| Entwicklung, Verstehen und Festhalten eines Gesamtbildes der Anwendung | 2 |
| Dokumentation als Kommunikationsunterstützung, nicht als Ersatz, vor allem in verteilten Umgebungen | 2 |
| Wissenssicherung für Übergaben von der Entwicklung zur Wartung | 2 |
| Wissenstransfer zwischen Projekten vor allem bei neuen Kompetenzfeldern | 2 |
| Verbesserung der Projektergebnisse (hinsichtlich Qualität, Kosten, Laufzeit) | 2/3 |
| Einbeziehung von verteilten Stakeholdern in die Kommunikation | 3 |
| Wissenstransfer bei Outsourcing/ Offshoring | 3 |
Die konkrete Ausgestaltung einer Dokumentation richtet sich immer nach der jeweiligen Zielgruppe. Dies betrifft bspw. den Detaillierungsgrad, die Inhalte, die gewählte Sprache. So erscheint relativ logisch, dass sich Source-Code-Dokumentation, Nutzerdokumentation und Management-Dokumente stark unterscheiden. Die nachfolgende Tabelle leitete aus den Zielstellungen aus dem Abschnitt Warum dokumentieren? die jeweils angesprochene Zielgruppe ab.
| Ziele | Zielgruppe | Stufe |
|---|---|---|
| Nachvollziehbarkeit von (Design-) Entscheidungen | Kundenvertreter | 1 |
| Interne Wissenssicherung, nicht-funktionale Anforderungen, Nachvollziehbarkeit von (Design-) Entscheidungen | Interne Entwickler | 1 |
| Kommunikationsunterstützung vor allem in verteilten Umgebungen, Gesamtbild ermöglichen, Übergaben von der Entwicklung zur Wartung | 2 | |
| Verbesserung der Projektergebnisse (Qualität, Kosten, Laufzeit) | 2/3 | |
| Wissenstransfer bei Outsourcing | Externe Entwickler | 3 |
| Einbeziehung von verteilten Stakeholdern in die Kommunikation | Interne und/oder externe Stakeholder | 3 |
| Nr. | Gewählte Zielstellung | Hauptsächliche Inhalte | Stufe |
|---|---|---|---|
| 1 | Wissen/Erfahrungen sichern | Projektüberblick mit Zielstellung, zentrale Anforderungen, Gesamtbild als Architektur-/Design-Modell, Besonderheiten/Lessons Learned | 1 |
| 2 | Nachvollziehbarkeit von (Design-) Entscheidungen ermöglichen | Entscheidungen bzgl. Umsetzungsalternativen, Abnahmen bzw. Change Requests von Funktionalität | 1 |
| 3 | Nicht-funktionale Anforderungen festhalten und berücksichtigen | Nicht-funktionale Anforderungen | 1 |
| 4 | Entwicklung, Verstehen und Festhalten eines Gesamtbildes der Anwendung | Software-Architektur/ Design-Modell | 2 |
| 5 | Dokumentation als Kommunikationsunterstützung vor allem in verteilten Umgebungen | Wie Nr. 1 plus Wissen über die Anwendungsdomäne | 2 |
| 6 | Wissenssicherung für Übergaben von der Entwicklung zur Wartung | Wie Nr. 4 plus Testinformationen | 2 |
| 7 | Wissenstransfer zwischen Projekten vor allem bei neuen Kompetenzfeldern | Wie Nr. 1 plus Lösungswege und Anleitungen und konkret umgesetzte Lösungselemente (Code-Fragmente) | 2 |
| 8 | Verbesserung der Projektergebnisse (Qualität, Kosten, Laufzeit) | Wie Nr. 6 und Nr. 7. | 2/3 |
| 9 | Einbeziehung von verteilten Stakeholdern in die Kommunikation | Wie Nr. 2 plus Projektüberblick | 3 |
| 10 | Wissenstransfer bei Outsourcing/ Offshoring | Nr. 5 plus Nr. 6 | 3 |
| Inhalt (WAS) | Dokumente (WELCHE) |
|---|---|
| Projektüberblick mit Zielstellung, zentralen Anforderungen | Projekt-/Produktsteckbrief |
| Product Backlog (Requirements) | |
| Gesamtbild als Architektur-/Design-Modell | Architektur-Dokument |
| Testinformationen | Testpläne und -ergebnisse |
| Besonderheiten/Lessons Learned | Lessons-Learned-Dokument |
| Entscheidungen bzgl. Umsetzungsalternativen, Abnahmen bzw. Change Requests von Funktionalität o.ä. | Projektverlaufsdokument/ Meeting-Protokolle |
| Lessons-Learned-Dokument | |
| Nicht-funktionale Anforderungen | Non-functional Product Backlog |
| Wissen über die Anwendungsdomäne | Unternehmensarchitekturdokument |
| Glossar | |
| Lösungswege und Anleitungen | How-To-Dokument |
Verfechter agiler Methoden betonen oft, dass „gerade genug“ dokumentiert werden sollte, wobei leider offen bleibt, wieviel gerade genug bedeutet. Um diese Maß beurteilen zu können, sollen die nachfolgenden Anregungen helfen:
| Dokument | Umfangsbegrenzung |
|---|---|
| Projekt-/Produktsteckbrief (o.ä.) | Produktüberblick 100 Wörter + Zielstellung 100 Wörter |
| 5-200Sätze (1 DIN A4-Seite) | |
| Architektur-Dokument | 1.000 Wörter |
| Non-functional Product Backlog (o.ä.) | Qualitätsmerkmale in je kurzen (2–3 Sätze) Beschreibungen |
| Unternehmensarchitektur-dokument (o.ä.) | kurze Beschreibung (1-2 Sätze) für jedes Fremdsystem und jeden Benutzertyp sowie Randbedingungen in ein paar kurzen Sätzen. |
Folgende konkrete Dokumentationsempfehlungen (vgl. Rüping 2003, S. 40–81) sind für die Dokumentation hilfreich:
| Kriterium | Stufe 1 | Stufe 2 | Stufe 3 |
|---|---|---|---|
| Dokumentation Komponentenebene | Jeder Entwickler für seinen Bereich | Jeder Entwickler für seinen Bereich | Dokumentar(e) |
| Dokumentation Gesamtsystemebene | Gemeinsam alle Entwickler | Dokumentar | Dokumentar(e) |
| Grundprinzip | 4-Augen-Prinzip | ||
| Abnahme | Projektleiter, Product Owner, Scrum-Master o.ä. | ||
| Dokument | Projektstart | Sprint-Start | Im Sprint | Sprint-Ende | Projektende |
|---|---|---|---|---|---|
| Projekt-/ Produkt-steckbrief | Anlegen | Überprüfen | |||
| Product Backlog | Anlegen | Neue Issues hinzufügen | Issue-Status ändern, kommentieren | Issues schließen | Letzte Issues prüfen/ schließen |
| Non-functional Product Backlog | |||||
| Architektur-Dokument | Anlegen | Überprüfen | |||
| Testpläne und –ergebnisse | Testpläne definieren | Tests nach Feature-Fertigstellung | |||
| Lessons-Learned-Dokument | Bei Feststellung anlegen | In Sprint-Retrospektive aktualisieren | Im Projekt-debriefing erstellen | ||
| Unternehmensarchitekturdokument | Anlegen | Bei Bedarf aktualisieren | Überprüfen | ||
| Glossar | Anlegen | Bei Bedarf aktualisieren | |||
| Projektverlaufsdokument/ Meetingprotokolle | Anlegen | Sprint-Planning-Protokoll | Wichtige Ereignisse aktualisieren | Sprint-Review-Protokoll | |
| How-To-Dokumente | Bei Bedarf erstellen/aktualisieren |