Eigentlich wollte ich diesen Text Dokumentation von Code nennen, mir ist aber beim Schreiben aufgefallen, dass dieses Thema viel grösser ist.

Mich wurmt das Thema Dokumentation schon seit meines Studiums. Wir haben viel von Projektorganisationstechniken, wie Agile, Wasserfall oder V-Modell gelernt. Wir haben DevOps in einer Tiefe besprochen, dass es einem schon wieder an den Ohren auslief. Aber das Thema Dokumentation wurde immer nur sehr holzschnittartig betrachtet.

Jedes Mal, wenn es zur Sprache kam, wurde nur auf Softwaresysteme, wie JavaDoc, Doxygen und PHPdoc verwiesen. Damit dokumentiert man Code. Nicht zu viel, damit nicht bei jeder Änderung die Dokumentation angepasst werden muss und nicht zu wenig, sodass es praktisch nutzlos für das Verständnis wird. Für den „Rest“ gibt es UML, einen Standard der sehr präzise ist, aber derartig wenig Freiraum lässt, dass ich praktisch niemanden kenne, der ihn Standardkonform verwendet. Klassendiagramme sind dabei mein Lieblingskonstrukt, sie werden sehr schnell unübersichtlich ab einer gewissen Projektgröße, sodass man sich durch verschiedene Ebenen der Abstraktion bewegt, man aber ohne wochenlange Einarbeitung an der geistigen Speicherkapazität scheitert, wenn man in der dritten Ebene angekommen ist und nicht mehr weiß, was man ursprünglich suchte.

Ein Drama in mehr als 40 Wörtern.

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.

They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.

• Youtube.com: PyCon AU 2017 - Daniele Procida: What nobody tells you about documentation