Wie organisiert man die Projektdokumentation? Wann wird aus einer Projektdoku eine Produktdoku? Dieser Artikel beleuchtet wichtige Eigenschaften von Dokumentationsartefakten und will helfen, Dokumentationsvorgänge besser zu planen und zu managen.
Use Cases für Dokumentation
Für die Nutzung der erstellten Dokumentation gibt es viele Use Cases:
- Rückgriff auf Entscheidungen: Wer hat welche Designentscheidung zu verantworten?
- Identifikation von Detaillösungen: Wie funktioniert eine Systemkomponente im Detail?
- Beschreibung von Wartungsvorgängen: Was ist im Betrieb zu beachten?
- Testdokumentation: Wie kann eine Komponente getestet werden, wenn zB Weiterentwicklungen geplant sind?
Die oben stehenden Beispiele zeigen, dass unterschiedliche Kontexte für die Dokumentationsnutzung vorstellbar sind: Der Projektkontext („wer hat warum etwas entschieden“), der Produktkontext („wie verhält sich ein Systembaustein“).
Diese Unterscheidung ist deswegen so wichtig, weil die Dokumentation meistens während der Softwareentwicklung, also im Projektkontext erfolgt. Während der Entwicklung ist die Wahrnehmung eines Entwicklers in der Regel sehr fokussiert auf aktuelle Stories – bestensfalls ausdehnbar auf den aktuellen Sprint. Ist bei der Dokumentation vorwiegend eine Projektdokumentation zu erstellen, so schadet dieser Fokus nicht. Wenn aber eine Produktdokumentation zu erstellen ist, so interessiert nicht, warum, und wann etwas entwickelt (oder zum wiederholten male geändert wurde), sondern es gilt den Status Quo des Produktes in der Dokumentation nachzuziehen.
Unterschiede zwischen Projekt- und Produktdokumentation
Warum sollte man überhaupt unterscheiden zwischen Projekt- und Produktdokumentation? Ist das im Endeffekt nicht das selbe? Das Projekt hat doch zum Ziel, ein Produkt zu erstellen. Am Projektende hab ich mit meiner Projektdokumentation doch eine Produktdokumentation, oder?
Das ist leider nicht so, und zwar aufgrund unterschiedlicher Anforderungen an Dokumentationen. In Projekten – speziell in agilen – ist es nicht unüblich, dass Features in mehreren Entwicklungszyklen überarbeitet werden. Es ist richtig und wichtig, alle Überarbeitungsschritte in der Projektdokumentation aufzunehmen – spätestens dann, wenn der Aufwand durch die Decke geht und der Kunde fragt, warum das alles so teuer ist, ist diese Dokumentation bares Geld wert.
Projektdokumentation darf veralten – sie hat Archivcharakter.
Bei der Beschreibung eines Produktes dagegen interessiert nicht der Werdegang (und die Zyklen) der Entwicklung, sondern nur der Status Quo. Wer wissen will, wie ein Produkt funktioniert, will wissen, wie es jetzt funktioniert.
Produktdokumentation muss aktuell sein – sie muss konsolidiert werden.
Typischerweise benötigt man beide Dokumentationsformen – Projekt- und Produktdokumentation. Und beide müssen(sollten) zeitnah zur Entwicklung erstellt bzw. konsolidiert werden.
Entwickler müssen in die Lage versetzt werden, den richtigen Ort für die Dokumentation zu finden. Um (archivierbare) Projektinfos abzulegen; um Produktinformationen zu erstellen oder zu konsolidieren. Im sprintDoc Projekt befassen wir uns sehr detailliert mit diesen Fragestellungen, und haben auch ein Plugin für Wikis und PM Werkzeug geschrieben, welches passende Dokumentationsstellen automatisch aufzeigt (auf Basis des modifizierten Quellcodes der Anwendung). Wir nennen die Komponente MagicMatcher.
Am Besten ist es natürlich, wenn man keine Werkzeuge dafür braucht – weil der Entwickler die Dokumentation selber als Referenz während der Entwicklung verwendet. Dies gelingt nur mit entsprechender Vorplanung und Vorstrukturierung. Auch hiermit befassen wir uns im sprintDoc Projekt, indem wir ein Methodenset für die Dokumentationsprozesse entwickeln.
Dokumentationsmuster
Es bietet sich an, für die verschiedenen Dokumentationen Patterns vorzulegen, die – anpassbar für den jeweiligen Zweck – ein Gerüst, einen Korridor für die Dokumentation vorgeben. Ein Katalog dieser Patterns wird in Kürze hier auf dieser Website veröffentlicht. Mit diesen Patterns ergeben sich sinnvolle Gebrauchsmuster sowohl für die Produkt- als auch für die Projektdokumentation, wobei noch einige Fragen offen sind. Ein konkretes Problem, welches wir noch auf dem Tisch haben, befasst sich mit der Anforderungsdokumentation.
Anforderungsdokumentation
Im (agilen) Projekt werden Produktfeatures in Form von Stories formuliert und umgesetzt. Je genauer (kleiner) diese Stories spezifiziert sind, umso berechtigter ist die Hoffnung, am Sprintende auch alles umgesetzt zu haben. Die Stories/Requirements lassen sich in agilen PM Tools managen. Nun beginnen Projekte aber nicht mit einem prall gefülltem Backlog voller Stories, sondern mit Anforderungen/Requirements, die der Kunde (oder der Dienstleister als treuer Vor-, Nach- und Weiterdenker) formuliert, und die in dieser Form auch Auftragsgegenstand sind. Spätestens zum Zeitpunkt der Endabnahme (auch agile Projekte müssen irgendwann donedone sein) wird das Produkt gegen diese Requirements geprüft.
Es ist also naheliegend, ein Anforderungshandbuch (die Requirements) in der Projektdokumentation mitzuführen und die Stories kontinuierlich mit den Requirements abzugleichen. (und fleißig zu dokumentieren, wenn der Kunde eine Überarbeitung/Änderung will – aber das nur am Rande).
Kommen wir zurück zum Problem mit der Anforderungsdokumentation: Requirements sind Auftragsbeschreibungen und müssen mitgeführt werden. Häufig wird in diesen Requirements detailliert dokumentiert, wie sich ein System zu verhalten hat. Entspricht das dort beschriebene Verhalten auch dem tatsächlichen Produktverhalten, so gehört diese Dokumentation auch in die Produktdokumentation. Für unsere Dokumentationsprozesse bedeutet dies: Wir brauchen Verfahren (Werkzeuge oder auch „nur“ manuelle Methoden), um aus Projekt-Requirements Produkt-Features zu machen. Wobei wir dann eben doppelte Dokumentation vorliegen haben – in der Projektdokumentation eventuell veraltet, in der Produktdokumentation stets aktuell.