Dokumentation muss strukturiert sein, damit sie genutzt wird

Dokumentation ist kein Selbstzweck, sondern soll verschiedenen Lesertypen die notwendigen Informationen für die Arbeit bereitstellen. Dafür benötigt man neben guten Inhalten auch eine gute Struktur.

In agilen Teams entstehen hauptsächlich technisch geprägte Dokumente. Selten werden diese wie Romane von vorne bis hinten am Stück gelesen. Vielmehr versucht der Leser die Inhalte so zu filtern, dass er möglichst schnell an die gewünschte Information herankommt. Dabei können wir ihn unterstützen.

Eine einfache Herangehensweise ist dabei, lieber mehr Struktur zu geben als zu wenig. Nach spätestens 4-5 Absätzen sollten man einen neuen Abschnitt beginnen und eine passende, sprechende Überschrift dafür finden. Passend dazu soll die Gliederung so aufgebaut sein, dass sich Inhalte nicht überlappen und unterschiedliche Perspektiven nicht vermischt werden. So sollten fachliche und technische Aspekte getrennt voneinander beschrieben werden. Auch der Nutzerfluss im Umgang mit der Software sollte getrennt von der detaillierten Oberflächenbeschreibung passieren.

Es muss auch nicht immer Fließtext sein. Oft helfen Tabellen oder Diagramme weiter und transportieren den Inhalt wesentlich schneller und kompakter. Ein Wiki bietet dafür schon viele gute Ansätze. Durch intelligente Verknüpfungen kann man kompakte und übersichtlich gliedern und dennoch wichtige Themen detailliert beschreiben.

Referenzen:

• Dokumentation in agilen Projekten – Andreas Rüping