Was macht eine gute Doku aus?

Dokumentationen sind geliebt und gehasst zugleich. Sie müssen erstellt werden, sie müssen stimmen, sie müssen aktuell sein. Doch was macht eine gute Doku aus? Für wen ist die Dokumentation gedacht und wie wird sie benutzt? Was muss in der Doku enthalten sein? Sie sehen schon, es gibt viele Wege, sich diesem Thema zu nähern. Aus dem Grund machen wir auch eine kleine Serie dazu. Teil befasst sich mit dem Medium, also dem Format der Dokumentation.

Viel Spaß beim Lesen.

Wo stand das wieder und wie ging das noch?

Man findet sie fast überall… auf längst vergessenen Laufwerken, in Ordnern mit dem Namen Archiv… aber auch hoch frequentiert aufgerufen im Intranet, vielleicht sogar auf der Firmenwebsite! Gerade im IT-Sektor ist jeder schonmal in irgendeiner Form mit der ein oder anderen Dokumentation in Kontakt gekommen. Die Bandbreite der in Dokumentationen beschriebenen Themen ist dabei bestimmt so groß, wie die Ausprägungen von Qualität und Mehrwert. Insbesondere durch die von der Digitalisierung geschaffenen Möglichkeiten eröffnen sich die unterschiedlichsten Varianten der Dokumentation.

Auf die Inhalte kommt es an

Wer im Internet recherchiert, findet genügend Templates für die unterschiedlichsten Formate von Dokus. Aber was macht denn eine gute Doku sonst noch aus? Hier legt jeder, je nachdem wie und für was er die Doku nutzt, sie aktualisiert oder verfasst, unterschiedliche Schwerpunkte. Diese Perspektiven unter einen Hut zu bekommen, kann oftmals Schwierigkeiten bereiten. Es macht daher Sinn sich bereits im Vorhinein klar zu werden, welche Aspekte zu einer guten Dokumentation führen. Natürlich hängt das Ganze auch schwer vom zu dokumentierenden Projekt, Produkt oder Service ab. Aus der Erfahrung heraus lassen sich aber gewisse Grundideen für gute Dokumentationen ableiten.

Form folgt der Funktion

Für den Anfang wollen wir einmal auf das Medium eingehen, in dem wir dokumentieren. Eine Dokumentation in Form einer Datei, sei es PDF oder Doc, mit Text, Diagrammen, Tabellen und Bildern haben die meisten schon einmal verwendet oder gepflegt. Vor allem wenn es sich um eine fertig entwickelte Version eines Produktes handelt, macht diese Form Sinn. Sie beschreibt in der Regel einen abgeschlossenen Zustand und wird mit dem Produkt ausgeliefert. Soll jedoch eine Datei als Doku zu einem System/Service dienen, der sich im stetigen Wandel befindet, so stößt man hier bei der Benutzerfreundlichkeit oft an Grenzen. Gerade, wenn mehrere Akteure an der Doku arbeiten, bzw. sie als Nachschlagwerk verwenden, kommt es oft zu Problemen. Die Doku liegt plötzlich in unterschiedlichen Varianten auf verschiedenen Laufwerken und die Arbeit mit und an der Doku wird inkonsistent. Durch die reine Digitalisierung unserer Dokumentation als Datei haben wir in diesem Fall also nicht viel gewonnen.

Online oder offline, das ist hier die Frage.

Digital heißt nämlich nicht gleich digital. Wer hier Abhilfe schaffen möchte und trotzdem nicht auf sein Dokument verzichten will, sollte auf Clouddienste wie „Sharepoint Online“ oder „Google Docs“ setzen. Diese Plattformen ermöglichen das Kollaborieren am selben Dokument und haben integrierte Versionierungsmechanismen. Der Inhalt ist somit stets aktuell und allen Akteuren zugänglich.

Eine weitere Möglichkeit Dokumentationen zu verwirklichen, bieten Webplattformen wie Confluence oder andere Wiki Systeme. Gerade wenn die Doku viele Referenzen sowohl innerhalb als auch nach außen zu weiteren Dokumentationen enthält, lassen sich diese sehr einfach durch Links innerhalb der Wiki Plattform umsetzen. So lassen sich unter anderem Redundanzen vermeiden und der Pflegeaufwand wird insgesamt geringer.

Eine weitere häufig verwendete Form der Dokumentation sind Webseiten. Diese Form eignet sich vor allem, wenn die Doku außerhalb der Firma für den Kunden zur Verfügung stehen soll. Gerade bei der Doku von Frameworks, Libraries oder APIs kann hier eine informative und aktuelle Doku Website die Akzeptanz und Nutzung bei Entwicklern steigern. Sie können neben klassischen Dokumentationsinhalten auch Videos und interaktive Elemente enthalten. Beispielsweise den Aufruf einer REST API direkt aus dem Browser heraus.

Sicher gibt es noch weitere Medien, in denen eine Dokumentation erstellt und gepflegt werden kann. Wir sehen aber bereits an diesen Beispielen, dass schon vor dem Erstellen der Dokumentation die Entscheidung für ein geeignetes Medium eine wichtige Rolle spielt. Für den weiteren Verlauf unserer Serie werden wir weitere Standpunkte und Fragestellungen beleuchten z.B.:

• Woran erkennen Sie auf den ersten Blick eine gute Dokumentation und was schreckt sofort ab?
• Was sind die größten Pain Points beim Schreiben oder Aktualisieren einer Doku? Wie vermeiden Sie diese?
• Für wen ist diese Doku gedacht? Wer wird sie lesen und was wird er/sie in der Doku suchen? Welche Inhalte müssen für wen wie aufbereitet sein?

Vorab würde uns schon interessieren, was für Sie eine gute Doku ist. Schreiben Sie uns doch in die Kommentare, welche Aspekte einer Doku relevant für Sie sind und welche nicht.

Freuen Sie sich auf die kommenden Artikel, wo wir genau diese Punkte im Detail beleuchten werden.