Das agile Manifest aus dem Jahr 2001 schätzt den Wert Funktionierende Software höher ein als den Wert Umfassende Dokumentation. Da Dokumentation immer auch mit Referenzen zwischen Informationen einhergeht, ist es interessant auch die Arten und Mengen von Traces zwischen Informationen zu hinterfragen und nicht nur die dokumentationswürdigen Inhalte an sich.
Neben dem Ziel, nur noch genau die Inhalte zu dokumentieren, die (langfristig) notwendig sind, wollen wir ein zweites Ziel verfolgen: die Anzahl von Traces minimieren und damit Pflegeaufwände einsparen.
Wir versuchen also das Thema Traceability auch im Sinne des agilen Manifests zu beleuchten und haben mit einer simplen Idee gute Erfahrungen in agil durchgeführten Softwareprojekten gemacht.
Um einen Teil von Traces nicht als Referenzen oder navigierbare Links pflegen zu müssen setzen wir eine einheitliche Struktur für verschiedene Dokumentationsartefakte ein. Wir nennen diese Struktur Ordnungsstruktur.
Die Grundidee: Baut man Dokumentationen unterschiedlicher Art und unterschiedlichen Inhalts immer mit der gleichen Strukturierung (Inhaltsverzeichnisse, Modellstrukturen, Testfallstrukturen, Struktur des Codes, …) auf, so spart man sich Referenzen zwischen den Inhalten der einzelnen Dokumente. Weil der Leser – hat er die Ordnungsstruktur einmal verinnerlicht – in verschiedenen Dokumenten immer in die gleichen Teilstrukturen navigiert um die gleichen Inhalte zu finden, müssen diese Inhalte nicht dokumentenübergreifend referenziert werden. Der Weg zum jeweiligen Inhalt ist durch die gemeinsame Struktur klar vorgegeben.
Um zu einer solchen Ordnungsstruktur zu gelangen, definiere man sich Strukturelemente. Dargestellt in einer kleinen Visualisierung lässt sich die Idee auch gut vermitteln.
Abbildung 1: Zur Strukturierung definierte Elemente (Beispiel)
Die definierten Strukturelemente und deren Beziehungen wendet man in unterschiedlichen Artefakten – gerne auch in unterschiedlichen Tools – an. Beispielhaft in einem Wiki für eine Produktdokumentation und in einem Testmanagementwerkzeug für die Strukturierung der Testfälle.
Abbildung 2: Beispielhafte (Ordnungs-)Struktur für eine Produktdokumentation
Gut funktioniert hat dieser Ansatz für Dokumentationsartefakte fachlicher Natur. Also z. B. Anforderungsdokumente oder einer Fachlichen Beschreibung/Produktdokumentation, einer Supportdokumentation oder eines Benutzerhandbuchs. Auch für die Strukturierung von Testfällen hat sich die Ordnungsstruktur bewährt. Schwieriger wurde die Einhaltung in den Codeartefakten. Zu Beginn noch nah an der gemeinsamen Struktur, hat sich die Zerlegung des Codes über die Zeit doch sehr von dieser entfernt.
Über die Betrachtung der notwendigen Dokumentationsartefakte im Projekt (begründet durch Fachlichkeit, Technik, Prozesse, Gesetze, Normen, Standards, andere Rollen, andere Organisationeinheiten, etc.) findet man heraus, welche Elemente aus der Struktur überhaupt und evtl. auch wie dokumentiert werden müssen. So müssen z. B. die Dienste aus dem Beispiel oben für eine Produktdokumentation und die Funktionen für ein Benutzerhandbuch beschrieben werden, die Komponenten jedoch nicht, weil diese in keinem Dokumentationsartefakt gefordert werden. Man dokumentiert also nicht jedes Element aus der Struktur, sondern nur diejenigen, die tatsächlich benötigt werden. Alle anderen Elemente dienen nur der Strukturierung.
Zurück zum agilen Manifest haben wir damit einerseits das unnötige Dokumentieren von Inhalten vermieden, die niemand fordert und andererseits auch mögliche Traces durch die einheitliche Struktur eingespart.