Das Lesen einer Dokumentation muss sich anfühlen, wie ein Sonntagsspaziergang im frühsommerlichen Elbsandsteingebirge und nicht wie eine Extrarunde durch einen militärischen Hindernisparcours nach einem Nachtmarsch mit 50 Kilorucksack. Um dies zu Erreichen muss der Dokumentierer folgende Leitplanken verinnerlichen.
Barkeeper
Schreibe die Dokumentation für Deinen Barkeeper! Er ist der ideale imaginäre Gesprächspartner, dem Du die fachlichen Zusammenhänge erklären musst. Er hat sicherlich in Deinem Fachgebiet keine Vorkenntnisse und kann, um sie zu verstehen, nur auf allgemein Bekanntes zurückgreifen. Diese Vorstellung zwingt Dich, Deine Gedanken und Aussagen auf eine Ebene herunterzubrechen, wozu sie klar und logisch sein müssen. Zu oft ist man selbst geneigt, Denkfehler durch Fachgeschwafel zu verdecken. Wenn Du für Deinen Barkeeper schreibst, geht das nicht. Auch schreibst Du Deine Dokumentation in der Regel für einen fachlich gemischten Leserkreis, bei dem jeder Leser vielleicht bei einzelnen Kapiteln Fachmann ist, bei anderen jedoch tatsächlich den Kenntnisstand Deines Barkeepers hat. Und selbst wenn Deine Leser in all Deinen Kapiteln Fachleute sind, so liest sich Deine Dokumentation in jedem Fall schneller und angenehmer, wenn Du sie für Deinen Barkeeper geschrieben hast.
Bilder
Ein Bild sagt mehr als 1000 Worte. Dies gilt uneingeschränkt auch für Deine Dokumentation. An jeder komplizierteren Stelle baue also Fotos ein, Screenshots (mit Greenshot geschossen und nachbearbeitet), Diagramme oder, wenn das am schnellsten geht, Handskizzen, die Du mit Deinem Handy abfotografierst.
Beispiele
Erfahrene Softwareentwickler kennen das: Wenn Sie durch googlen ein Problem lösen wollen, dann überspringen Sie auf der angebotenen Webseite oft den Text und scrollen gleich zum Codebeispiel. Oftmals reicht das nämlich schon aus, um die vorgeschlagene Lösung zu verstehen. Eine gute Dokumentation ist gespickt mit guten Beispielen, die mit ganz Konkretem das Allgemeine auf den Punkt bringend zeigen.
Trichter-Muster
Jedes Kapitel/Unterkapitel für sich muss einem Trichtermuster folgen. Trichter daher, weil möglichst jeder potenzielle Leser zu Beginn des Kapitels eingefangen werden soll – man soll ihn dort abholen, wo er sich bezüglich seines Wissensstandes befindet. Beginne also im Allgemeinen und Schritt für Schritt komme ins Konkrete. Beginne im Fachlichen und Schritt für Schritt komme ins Technische. Beginne im Bekannten und Schritt für Schritt komme ins Unbekannte.
CRUD-Muster
Zumindest in der Dokumentation von Software muss sich das CRUD-Muster abbilden. Egal um welche Entität es sich handelt, immer muss die Dokumentation beschreiben, wie man diese Entität erzeugen (CREATE), lesen/suchen/finden (READ), ändern (UPDATE) oder löschen (DELETE) kann – und zwar am besten, da am intuitivsten in eben dieser Reihenfolge.
Atomarität
Jedes Kapitel/Unterkapitel muss soweit wie möglich inhaltich abgeschlossen sein, sich also ohne allzuviel Vorkenntnisse selbst erklären. Da jedes Kapitel/Unterkapitel auch per Link erreichbar sein soll, wird ja von ganz anderen Kapiteln der Doku oder gleich von ganz außerhalb der Doku auf das Kapitel/Unterkapitel verwiesen. Der Leser erwartet also, zu Recht, dass er das Kapitel/Unterkapitel zumindest grob versteht, ohne alle Kapitel/Unterkapitel vorher genau gelesen zu haben.
ASS
„Acroynms Seriously Suck“ (Elon Musk) oder frei übersetzt: Abkürzungen sind kommunikatives Gift. Warum Elon mit drastischen Maßnahmen droht, wenn seine Mitarbeiter Abkürzungen verwenden, die nicht von ihm explizit authorisiert sind, erklärt der Großmeister am besten selbst: hier
… was bedeutet gleich nochmal ASS? …