Dokumentation von Produkt und Prozess

Artefakte

„We favor working software over comprehensive documentation“, Agile Manifesto, 2001.

Die obige Aussage aus dem Agile Manifesto bedeutet, dass lauffähige und funktionierenden Produkte/Software/Systeme wichtiger sind, als Dokumentation. Das bedeutet aber nicht, dass Dokumentation unwichtig wäre und komplett weggelassen werden kann. Ein wichtiges Kriterium bei Dokumenten ist daher, dass sie benötigt werden, speziell, ob sie auch gelesen werden, d.h ein echter Stakeholder-Need dahintersteht. In regulierten Systementwicklungen werden die zu erstellenden Dokumente und deren Inhalte vorgegeben. Diese müssen natürlich auch bei der Anwendung einer agilen Entwicklungsmethode erstellt und geliefert werden. Der Unterschied entsteht dabei in der iterativ-inkrementellen Erstellungsweise der Dokumente, parallel mit dem zu entwickelden Produkt. Da dabei viele Versionen der verschiedenen Dokumente entstehen, müssen die Dokumente sauber versioniert werden. Auch der dazugehörende Freigabeprozess muss einfach und unkompliziert sein.

Ein grundsätzliche Frage ist, welche Arten von Dokumentation benötigt werden und wie wir die Entstehung der Dokumente in unserem Entwicklungsprozess abbilden.

Arten von Dokumenten

  1. Prozessdokumentation:
    • Prozessbeschreibung und Leitfäden, auch Standard Operating Procedures (SOP)
    • Dokumentenvorlagen für die Produktdokumentation (Templates)
    • Prozess-Reviews und Audit-Reports
  2. Produktentwicklungsdokumentation:
    • Planungsdokumente
    • Statusreports
  3. Produktdokumentation:
    • Produktdokumentation folgt immer der Systemarchitektur und seinen Systemelementen, Modulen, Schnittstellen und Integrationsebenen
    • Spezifikationen (Anforderungen, Lösung, Tests)
    • Dokumentierte Entscheidungen (z.B. in Form eines Produkt-Design-Journals)
    • Testergebnisse und Reports
    • Freigaben und Zulassungen
    • Benutzerdokumentation (Use-Case-basiert oder Komponenten-basiert)

Grundsätzlich betrachtet das P4-Framework die benötigten Dokumente als Lieferobjekte, genauso wie andere Teile des Systems, wie z.B. die Produktions- und Testwerkzeuge. Daher ist es wichtig, für jede Produktentwicklung anfangs festzulegen, welche Lieferobjekte es neben dem zu entwickelnden Produkt geben soll. Die einzuhaltenden Normen und Standards geben zum Teil wichtige Hinweise über Form und Inhalt der Dokumente, z.B. die Normen ISO/IEC 13485, 14971, 60601 und 62366 in der Medizintechnik.

Viele der zu erstellenden Dokumente sind eng an das zu entwickelnden Produkt, seine Komponenten und deren Integrationen gekoppelt. Diese sollten dann auch in der Definition-of-Done des Reifegrads des jeweiligen Systemelements erscheinen (wodurch nebenbei der Entwicklungsprozess zum großen Teil beschrieben ist). Dadurch entsteht eine objekt-orientierte Backlog- und Dokumentenstruktur. Der Vorteil davon ist, dass das Produkt, die Komponenten und die Integrationen erst dann als abgeschlossen betrachtet werden, wenn auch die dazugehörende Dokumentation im vorgesehenen Reifegrad erstellt und freigegeben wurde. Dadurch wird ein eher schädliches Nachdokumentieren verhindert.

Entwicklungsdokumentation wird also iterativ-inkrementell erstellt, synchron zum Produkt und seinen Komponenten.

„Make is as simple as possible, but not simpler“, Albert Einstein.

Durch die rigiden Vorgaben werden die erstellenden Dokumente von den Entwicklern häufig als lästige Pflicht empfunden. Dies soll und muss nicht so sein. Die Prozessexperten und die Entwickler sollten die Dokumente daher so gestalten, dass sie sozusagen während der Arbeit entstehen und damit ein echtes Arbeitsmittel darstellen. Das bedeutet, dass die Werkzeuge zur Dokumentenerstellung einfach in der Bedienung sein müssen, sowie lästige Aufgaben idealerweise automatisch erledigen.

Wiederverwendung

Dokumente eignen sich sehr gut zur Wiederverwendung, insbesonders da sie heute meist in digitaler Form vorliegen. Die einfachste Form der Wiederverwendung stellt die Nutzung von Dokumentenvorlagen (Templates) dar. Meist werden diese Templates bei der Implementierung von Prozessstandards in einer Organisation erstellt und bestehen aus Dokumenten mit Kapitelüberschriften und ggf. ein paar Anweisungen zum Befüllen der Kapitel. Typischerweise müssen die Bearbeiter in den Projekten, dies Kapitel dann manuell ausfüllen, wobei übergreifende und einleitende Beschreibungen häufig aus anderen Dokumenten kopiert werden. Dies erzeugt Redundanzen, die bei jeder Überarbeitung angepasst werden müssen.

Diagramme als Dokumentation

„A picture replaces a thousand words“, unknown.

Dokumente werden so schlank wie möglich und durch Visualisierungen (z.B. mittels UML-Diagrammen) erstellt.

Automatisierung

„Don’t Repeat Yourself“: The DRY principle.

Bei der Erstellung muss darauf geachtet werden möglichst keine Wiederholungen zu erstellen (DRY- Prinzip), um bei Änderungen keine Redundanzen finden und pflegen zu müssen. Das Generieren von Dokumenten aus einem Satz von Stammdaten ist eine gute Technik dazu. Der Ansatz Docs-as-Code führt dies konsequent weiter und behandelt Dokumente wie Software-Code, der in kleinen Schritten erstellt und erweitert wird, versioniert und inkludiert wird und dabei immer aktuell gehalten wird.

Häufigkeit der Änderung von Dokumenten

Eines der wichtigsten Prinzipien der Agilen Produktentwicklung ist das iterative und inkrementelle Vorgehen und dabei möglichst früh überprüfbar oder sogar potentiell lieferfähig zu sein. Dies bedeutet, dass Produktfunktionen (Features & Capabilities) im laufe der Zeit nacheinander entwickelt werden, also hinzugefügt werden. Hierbei ist es notwendig, dass auch die zum Produkt gehörende Dokumentation in gleicher Art und Weise entsteht, um für eine Version des Produkts (aka Release) eine vollständige Dokumentation vorliegen zu haben. Somit ist das Produkt oder das System nach jeder Iteration oder jedem Zyklus vollständig. Dabei lässt sich die Umfang und der Reifegrad von Produktdokumentationen über die Art und Häufigkeit der Releases definieren (z.B. interne Test-Releases oder externe Releases für Kunden).

Nun können wir für die Produktdokumentation entscheiden, ob diese wie ein Modul zum System gehört (und wir diese als einen eigenen Liefergegenstand betrachten), oder wir die notwendige Dokumentation in der Definition-of-Done für das System oder seine Module betrachten.

Ebenfalls wird es immer auch Dokumentation geben, die auf Basis der integrierten Module zu einer Teilintegration oder dem voll integrierten System gehören, z.B. Modulspezifikationen oder Testspezifikationen und -berichte von Teilintegrationen.

Lebenszyklen von Dokumentationen

Iterativ-inkrementelle Dokumentenanpassung bedeutet nicht, dass sich alle Dokumente ständig ändern sollen. Es gibt grundsätzlich drei verschiedene Änderungszyklen mit unterschiedlicher Häufigkeit:

  1. Änderung für Prozessanpassungen. Diese sollten möglichst nur für neue Produktentwicklungen übernommen werden
  2. Änderungen für neue Produktentwicklungen oder neue Applikationen
  3. Änderungen bei Funktionserweiterungen eines bestehenden Produkts oder in einer laufenden Produktentwicklung (externes oder internes Release)