Surprising Documentation

Hi,

Klassenkommentare, Architekturdokumentation, Methodenkommentare, API-Dokumentation, Inlinekommentare, Featuredokumentation, Wireframes, Entity-Releationship-Diagramme, Use-Case-Diagramme, Processdokumentation, End-User-Dokumentation….

Es gibt so viele Dinge die man dokumentieren kann. Aber welche brauche ich wirklich?

Dokumentation schreibt sich nicht von alleine. Jemand muss sich dafür die Zeit nehmen. Und damit sie auch wirklich Mehrwert bringt muss sie gut geschrieben, möglichst vollständig und fokussiert sein. Das kann nicht jeder.

In großen Konzernen - mit tausenden Mitarbeitern - wird viel dokumentiert. Es gibt Softwarearchitekten, die die Zeit und Ausbildung haben gute Dokumentation zu schreiben. Es gibt so viele Entwickler, dass genügend Zeit eingeräumt wird den Code zu dokumentieren. Und technischer Autoren verfassen in höchster Qualität die End-User-Dokumentation.

Kleinere Teams können sich das nicht leisten.

Zu dokumentieren bringt auf den ersten Blick keinen Wert für das Produkt. Es ist nichts was der User sieht. Es ist nichts was der User benutzt (Außer der End-User Dokumentation).

Es ist gedacht für die Entwickler. Zum Onboarden neuer Mitarbeiter. Zum Festhalten von Entscheidungen. Zum Sortieren der eigenen Gedanken.

“Also welche Dokumentation sollte ich denn jetzt schreiben?”

Schreib die Dokumentation, die auch gelesen wird!

“Und welche Dokumentation wird gelesen?”

Keine veraltete. Oder Dokumentation von der du glaubst, dass sie veraltet sein könnte.

Eine Dokumentation über Klassen, Methoden und UI Elemente bringt keinen Mehrwert. Wenn ich das lese, dann glaube ich nicht, dass sie noch aktuell ist. Und es ist so schnell im Code oder in der Applikation nachgeschaut was der aktuelle Stand ist.

Konzentriere dich bei der Dokumentation auf Konzepte. Beantworte das “Warum”.

• Warum wurden die Services so geschnitten?
• Warum deployen wir auf folgende Hosts?
• Warum wurde Technologie X gewählt?
• Warum ist die Datenbank hier nicht normalisiert?

Dabei muss nicht das offensichtliche dokumentiert werden. Nein. Dokumentiere das überraschende. Verschwende keine Zeit damit das zu dokumentieren was sowieso jeder weis. Du brauchst auch nicht die Vorteile der JVM dokumentieren - das kann man woanders nachlesen.

Wenn du den Leser der Dokumentation durchgehend überraschst - dann hast du das richtige aufgeschrieben.

Rule the Backend,

~ Marcus