Diverses / Stolpersteine / Qualität der Dokumentation

Qualität der Dokumentation

➪ Wichtig für die Nutzung, aber auch für die Wartbarkeit einer Software ist ihre Dokumentation. Sie dient ebenso zu Nachweiszwecken über erbrachte Leistungen wie auch dem Know-How-Transfer zwischen den diversen Beteiligten eines Projekts, etwa wenn unterschiedliche Developer den Quellcode warten oder weiterentwickeln.

Eine gute Dokumentation besteht einerseits aus separaten Dokumenten wie Spezifikation, Testdokumentation oder Glossar. Anderersites besteht sie aus Kommentaren im Sourcecode, die die Bedeutung bestimmter Variablen erläutern, oder die erklären, warum eine bestimmte Logik angewendet wurde. Obwohl es für den Aufbau von Software-Dokumentationen Normen gibt, ist die Praxis teilweise ernüchternd.

Es beginnt damit, dass nicht alle Fachplaner in der Lage sind, eindeutig und unmißverständlich darzulegen, was genau das Ziel der Anwendung ist und welche Features erforderlich sind. Diesbezügliche Rückfragen der Entwickler mögen wohl Klärung schaffen; jene Zusatzinformationen werden jedoch nicht immer konsequent in der Dokumentation festgehalten. Das ist spätestens dann problematisch, wenn die Informationen nur im Kopf des Entwicklers stehen und dieser nach einiger Zeit das Unternehmen verlässt.

So stimmen nach Fertigstellung eines Projekts die Dokumentation und der Sourcecode nicht immer überein. Für einen neuen Entwickler, der in ein bestehendes Projekt einsteigen soll, kommt viel darauf an, sich schnell zurecht zu finden. Wenn die Arbeit jedoch - wegen fehlender oder qualitativ schlechter Dokumentation - mit einer zeitintensiven Forschungstätigkeit beginnt, kann der Liefertermin in Gefahr geraten.

Aber auch übernehmende Entwickler dokumentieren ihre aktuellen Recherche-Ergebnisse keineswegs immer. Und da der Liefertermin drängt, ist für eine ausführliche Dokumentation sowieso keine Zeit. Die Abweichungen Code / Dokumentation werden nicht behoben, sondern verschärfen sich möglicherweise noch.

Selbst wenn die Dokumentation erfolgt, ist sie nicht immer hilfreich. Teilweise wird sie in einem Umfang geführt, die ein intensives Studium der weit verzweigten Erläuterungen, Links und Hinweise erfordern. Wohl dem, der sofort weiss, wo er mit seiner Arbeit ansetzen muss!

Andere Dokumentationen sind nicht hilfreich, weil sie nur erklären, was aus der nächsten Quelltextzeile ohnehin klar hervorgeht ("// Loop über ...") oder wenn der Developer sich in Nebensächlichkeiten verliert, die Erläuterung von Grundgedanken und Leitideen jedoch unterlässt.

Wieder andere Dokumentationen fallen durch Kürze und Knappheit auf. In möglichst nur drei Worten wird die gesamte Komplexität von mehreren Tausend Quelltextzeilen ausgedrückt. Diese drei Worte mögen zwar präzise sein; hilfreich sind sie nicht, wenn die Komplexität der Problemstellung unbekannt ist. - Hilfreich ist auch nicht, Variablen, Programme oder Aliasse nicht mit sprechenden Namen zu benennen, sondern mit "a", "x" oder "hugo" - natürlich ohne jegliche Erläuterung.

Bedenklich ist der Ansatz, zuerst alles zu implementieren und die Dokumentation hinterher zu machen. Zwar ist eine systematische Syntax hilfreich, die erlaubt, dass Tools wie Javadoc aus dem Quellcode automatisch ein übersichtliches Dokument erzeugen. Dieses ersetzt aber weder eine solide, überschaubare Spezifikation noch fehlende Kommentare im Sourcecode.

Überproportional teuer wird eine fehlende oder qualitativ schlechte Dokumentation bei hoher Fluktuationsrate der Mitarbeiter. Während ein Entwickler, der seine Gedanken und Konzepte schriftlich niederlegt, dazu wenige Minuten braucht, benötigt jemand, der sich ohne diese Hilfe in die Thematik einlesen muss, dazu mehrere Stunden bis Tage. Mit Hilfe einer guten Dokumentation kann er das in einem Bruchteil der Zeit schaffen. Damit liegt der Zeitvorteil einer guten Dokumentation bei einem Vielfachen jener kurzen Dauer, die nötig ist, sie zu erstellen.

Beim Entwickeln in großen Teams ist hilfreich, sämtliche separaten Dokumente mithilfe eines leistungsfähigen Dokument-Managementsystems zentral abzuspeichern. Die Leistungsfähigkeit jener Software gehört zur Dokumentationsqualität. Systeme, bei denen wesentliche Informationen gelöscht werden müssen, um eine bestimmte Systematik einzuhalten, sind hier wenig geeignet.

wg / 22. Mai 2021

---

---

Fragen? Anmerkungen? Tipps?

Bitte nehmen Sie Kontakt zu mir auf.

---