Dokumentation von Software Projekten

von Mathias Schnauder, Software Entwickler bei Sellmore

Die Dokumentation stellt in Unternehmen eine große Herausforderung dar. Es gibt viele Aspekte, die zu berücksichtigen sind. Das beginnt mit einfachen Dingen, wie die Zeit und Arbeitskraft, die zum Erstellen und zur Aktualisierung einer Dokumentation benötigt wird. Für eine sinn- und maßvolle Dokumentation müssen jedoch weitere Überlegungen angestellt werden.

Überlegungen

Zunächst muss über die Art der Dokumentation nachgedacht werden. Handelt es sich um eine einfache Dokumentation von erledigten Tätigkeiten, reicht meist ein System von Checklisten. Ist das Ziel hingegen die Konservierung von Wissen, ist es notwendig, komplexe Zusammenhänge auszuformulieren und in Schriftform abzubilden. In diesem Moment wird eine Dokumentation nicht mehr zwei-, sondern mehrdimensional.

Dokumentiert man komplexes Wissen, ist es auch da nicht möglich, das gesamte Wissen linear in Form eines Aufsatzes zu verfassen. Ziel muss stattdessen sein, Wissen so abzulegen, dass der Nutzer es sich nach seinen momentanen Bedürfnissen, seinem Blickwinkel und der von ihm gewünschten Informationsdichte abrufen kann.

Stichwort Informationsdichte: Auch das ist ein Aspekt, der in Erwägung gezogen werden muss. Ein Aufsatz hat wegen seiner Menge an Informationen eine relativ geringe Dichte, wohingegen eine Tabelle eine sehr große Informationsdichte aufweist. Trotzdem ist nicht jede Form von Informationsdichte für jede Form von Information oder jede Form von Nutzer geeignet.

Jeder Nutzer betrachtet eine Dokumentation aus verschiedenen Blickwinkeln. Ein Projektleiter sortiert seine Dokumentation vielleicht nach Thema, während ein Programmierer die gleichen Informationen nach der Art der eingesetzten Technologie gliedert. Ein Supportmitarbeiter wiederum benötigt keine Übersicht, sondern eine konkrete Fachinformation, um ein Problem lösen zu können.

Beispiele

Die derzeit beste Form, die oben genannten Überlegungen unter einem Hut zu bringen, bieten derzeit Wikis. Es gibt eine Reihe von Beispielen im Internet, wie Spiele-Wikis oder Fan-Wikis von Fernsehserien, bei denen eine große Menge an Nutzern Content in eine Wikipedia einpflegen, wobei dennoch eine Form gewahrt und Wildwuchs vermieden wird. Zugleich sind die Informationen aus allen erdenklichen Blinkwinkeln und Informationstiefen abrufbar. Sie sind leicht auffindbar und der Lese- bzw. Informationsfluss wird selbst über verschiedene Informationsdichten hinweg nicht unterbrochen. Schauen wir uns an, welche Werkzeuge dort verwendet werden:

Moderation. Je mehr Nutzer Inhalte in eine Wikipedia einpflegen, desto wichtiger werden Moderatoren. Sie pflegen eine Struktur ein, indem sie leere (oder rudimentäre) Beiträge anlegen, die dann von anderen Nutzern nur noch gefüllt werden. Und sie kuratieren die Inhalte, editieren, ergänzen und löschen Teile oder ganze Beiträge.

Verlinkung. Wird in einem Beitrag zum Beispiel das Wort „Schauspieler“ erwähnt, wird dieses Wort zu einer Liste aller Schauspieler verlinkt. Von dort kann man wieder in die Tiefe gehen, indem man einen der dort aufgelisteten Einträge öffnet. Alternativ dazu ist jeder Schauspieler aber vielleicht mit einer Episode, einer Staffel oder einem anderen Thema verlinkt, so dass der Nutzer die Wahl hat, an den für ihn interessanten Stellen weiterzulesen. So hat der Nutzer die Möglichkeit, sich an einem roten Faden entlang durch verschiedene Informationsebenen zu navigieren.

Erwähnenswert ist dieser Punkt deshalb, weil er oft vernachlässigt wird. Verlinkungen herzustellen ist in den meisten Dokumentationssystemen aufwendig, insbesondere bei fehlender Moderation und dem damit verbundenem Wildwuchs. Wird darauf verzichtet, so ist der Nutzer angehalten, etwa über die Suchfunktion selbst nach weiterführenden Informationen zu suchen.

Dies hat aber enorme Nachteile. Erstens wird der Lese- und Informationsfluss gestört, insbesondere dann, wenn der Nutzer zur Suche die aktuelle Seite verlassen muss. Weiterhin muss der Nutzer wissen, nach welchem Begriff er sucht. Gerade bei Volltextsuchen ist die Ergebnisliste zu ungenau. Sucht er nach dem Wort „Schauspieler“, so liegt es in seiner Verantwortung, aus den zwanzig Ergebnissen, in denen das Wort vorkommt, denjenigen herauszufinden, in dem die Liste aller Schauspieler hinterlegt ist.

Verlinkungen sind also eine Einladung zum Weiterlesen und somit als Führung durch das Informationsangebot zu verstehen. Sie sind enorm wichtig, um komplexe Zusammenhänge herzustellen ohne dabei das Risiko des Verirrens in Kauf zu nehmen.

Synonyme. Beim Dokumentieren steht man oft vor dem Problem, wie man die Informationen sortiert. Nehmen wir als einfaches Beispiel eine Dokumentation über Bäume. Ist jeder Baum so anders geartet, dass es sich lohnt, dafür eine eigene Seite zu schreiben? Oder unterscheiden sich die meisten Bäume nur unwesentlich in bestimmten Details, so dass eine Seite ausreicht, in denen lediglich auf kleine abweichende Details eingegangen wird?

Synonyme bieten dem Nutzer die Möglichkeit, nach verschiedenen Suchbegriffen zu suchen und trotzdem an die richtige Stelle geleitet zu werden. Dabei ermöglichen Sie es dem Verfasser, Informationen so zu hinterlegen, dass er Informationen in verschiedenen Informationsdichten nicht mehrmals hinterlegen muss.

Egal also, ob der Nutzer nach „Apfelbaum“, „Kirschbaum“, „Kirschbäume“, „Kirsche“ oder „Forstwirtschaft“ sucht, er wird stets auf die richtige Seite geleitet, von der aus er sich mittels Verlinkung in die gewünschte Informationstiefe navigieren kann.

Prüfung und Freigabe. Zusammen mit der Moderation ist eine Prüfung und Freigabe sinnvoll. Bei Wikipedia gang und gebe, um die Form zu wahren und Missbrauch vorzubeugen, ist dies außerdem eine gute Möglichkeit zur Verteilung von Wissen. Im alltäglichen Geschäftsprozess könnte dies zum Beispiel im Rahmen einer Abnahme einer Lösung durch den Projektleiter erfolgen.

Erkenntnis

Fassen wir also noch einmal zusammen: Dokumentation ist die Kunst, mehrdimensionale Informationen so miteinander in Einklang zu bringen, dass unterschiedliche Nutzer diese Informationen aus verschiedenen Blickwinkeln und in selbst gewählten Portionen abrufen können.

Ist dieses Ziel erreicht, ist die Frage nach dem „Wie viel dokumentieren“ und „Wie tief dokumentieren“ gar nicht mehr so entscheidend. Eine gute Organisation ist daher nicht mehr so aufwendig, wie man zunächst glauben mag.

Das System, welches zur Dokumentation eingesetzt wird, muss über die entsprechenden technologischen Möglichkeiten verfügen. Dies ist bei den meisten Wiki-Systemen heutzutage der Fall. Wichtig ist hierbei, dass die Werkzeuge einfach zu bedienen sind, denn der Verfasser einer Dokumentation soll sich mit seinem Inhalt und nicht mit der Bedienung des Systems beschäftigen.

Unter dem Strich lassen sich Dokumentation sehr wohl in den alltäglichen Geschäftsprozess einflechten. Kombiniert man Vorgänge, die derzeit noch fernab der Dokumentation mündlich oder per E-Mail geschehen, so ist es möglich, zwei Fliegen mit einer Klappe zu schlagen. Betrachtet man zum Beispiel eine Aufgabenstellung bereits als Teil der Dokumentation, so kann man deren schriftliche Ausformulierung– die ja ohnehin vom Projektleiter angefertigt wird – bereits als ersten Teil eines Themas und somit als Bestandteil der Moderation verstehen.

Dokumentation ist und bleibt ein umfangreiches und schwieriges Thema. Wer glaubt, er könne Ressourcen sparen und Dokumentation „nebenbei“ von seinen Mitarbeitern „miterledigen“ lassen, der irrt sich. Aber mit ein wenig Aufwand, einigen einfachen Regeln und einer durchdachten Herangehensweise ist diese Aufgabe zu bewältigen.