Softwaredokumentation: Tipps für mehr Freude und Effektivität
Vier Experten teilen ihr Wissen darüber, wie Entwickler ihre Software zielgerichteter und weniger mühsam dokumentieren können. Teils kann KI dabei helfen.
(Bild: Stokkete/Shutterstock.com)
(This interview is also available in English.)
Softwaredokumentation kann nervenzehrend sein – doch das muss sie nicht. iX hat vier Experten zu ihren Erfahrungen und Verbesserungsvorschlägen befragt. Charlotte Scharbert, Alexander Schwartz, Falk Sippach und Dr. Gernot Starke geben Einblicke, wie hilfreich KI-Tools derzeit sind, welche Best Practices Entwicklerinnen und Entwickler anwenden können, welche Fallstricke sie vermeiden sollten und wie sich Dokumentation nahtlos in den Arbeitsalltag integrieren lässt.
Gängige Hürden: Fehlende Wertschätzung, unklare Zielgruppen und Anweisungen
iX: Die Dokumentation von Software und ihrer Architektur hat den Ruf, nicht sonderlich beliebt zu sein. Was sind dabei eurer Meinung nach die größten Hürden?
Charlotte Scharbert: Ich denke, ein großes Problem ist, dass es keinen Standard dafür gibt, wie in der Architektur für Grundrisse von Häusern oder in der Elektrotechnik für Schaltpläne. Natürlich haben wir Standards wie UML, die aber kaum genutzt werden und meiner Erfahrung nach nur bedingt dazu geeignet sind, Softwarearchitektur abzubilden. Daher findet man häufig eine wirre Anordnung von "boxes and lines", die nach ein paar Monaten niemand mehr richtig versteht, oder in der Projektdokumentation steht einfach nur "wir verwenden eine hexagonale Architektur" mit einem Bild aus der Google-Suche – und das war's. Oft wird die Dokumentation erst am Ende eines Projektes erstellt. Dann ist es schwer, sich noch an alles zu erinnern oder nachzuvollziehen, wie etwas aufgebaut ist. Das macht das Dokumentieren langwierig und nervenraubend.
Dazu kommt, dass es wenige Tools gibt, mit denen man schnell und simpel Diagramme erstellen kann, die sich bei Änderungen später einfach anpassen lassen. Meiner Erfahrung nach führen grafische Tools schnell zu Frust, weil Entwicklerinnen und Entwickler keine halbe Ewigkeit Kästchen verschieben möchten. "Diagrams as code" ist da ein guter Ansatz, hat meiner Meinung nach aber noch nicht sein volles Potenzial erreicht.
Alexander Schwartz: Die fehlende wahrgenommene Wertschätzung der Dokumentation ist eine häufige Hürde. Bei Entwicklerinnen und Entwicklern ist Dokumentation immer dann unbeliebt, wenn sie nicht sehen, dass sie gelesen und aktiv genutzt wird. Dort kann man ansetzen: Ein Webtracking-Tool kann zeigen, welche Teile der Dokumentation wie oft aufgerufen werden, während eine Statistik von vermeidbaren Kundenanfragen darauf hinweisen kann, wo Dokumentation fehlt. Eine Softwarearchitektin oder eine Fachabteilung können ihre Wertschätzung gegenüber der Dokumentation zeigen, indem sie sie lesen und Fragen dazu stellen, um das jeweilige System zu verstehen. Man kann sich selbst zum Beispiel fragen, wann man das letzte Mal einen Auszug aus der Dokumentation oder eine Grafik daraus zu einem Planungsmeeting mitgenommen und aktiv damit gearbeitet hat, anstatt das Diagramm neu auf einem Flipchart zu skizzieren. Dokumentation kann eine Investition in die Zukunft sein, doch sie wird manchmal als das Gegenteil wahrgenommen: Man könnte sich fragen, ob man seinen Job verliert, wenn man zu viel dokumentiert. Dabei hilft Dokumentation den Stakeholdern, ein System zu verstehen, und regt zu neuen Ideen an. Und neue Ideen für ein bestehendes System sind eine gute Voraussetzung dafür, den aktuellen Job zu behalten.
Entwickler klagen oft darüber, überlastet zu sein und keine Zeit zu haben, Dokumentation zu schreiben. Andererseits verbringen sie viel Zeit damit, anderen Teammitgliedern Dinge zu erklären, die sie mit guter Dokumentation nicht erklären müssten. Und wenn Verstärkung ins Team kommt und keine Dokumentation vorhanden ist, dann ist das neue Teammitglied schnell frustriert und wieder weg.
Bei Systemen ohne Dokumentation wird sehr schnell der Rotstift angesetzt. Laut meiner Erfahrung gab es spätestens alle zwei Jahre eine Bestandsaufnahme der verschiedenen Systeme. Wenn niemand erklären kann, wofür das System zuständig ist, wie es funktioniert und welchen Mehrwert es bringt, ist das meist schlecht für die Zukunft des Systems und des Teams. Nur selten gelingt es einem System zu überleben, wenn andere schlichtweg Angst davor haben, es abzuschalten, weil niemand weiß, was es tut.
Manchmal besteht die Hürde für das Schreiben von Dokumentation aus einer Mischung aus fehlender Gewohnheit und hoher kognitiver Belastung – nicht nur für Architekturdokumentation. Hat man das lange nicht mehr getan, fällt es schwer, spontan die passende Dokumentation zu ergänzen, die Teil einer aktuellen Softwareänderung wäre. Zu wenig Struktur oder zu viele Formalismen führen dazu, dass Autoren zu viel über das Drumherum nachdenken müssen, anstatt sich auf das Schreiben der zusätzlichen Abschnitte oder das Erstellen der neuen Diagramme zu konzentrieren. Bei Softwarearchitekten und anderen Stakeholdern ist Dokumentation immer dann unbeliebt, wenn sie nicht aktuell ist. Sie können sie trotzdem aktiv nutzen, sie als Versicherung für die Zukunft bewerben und mit einfachen Strukturen und Werkzeugen ihre Pflege vereinfachen. Außerdem hilft es, mit gutem Beispiel voranzugehen und in Absprache mit den Eigentümern selbst mitzuschreiben. Ich empfehle, die Wissensträger zu interviewen, die Dokumentation selbst anzupassen und die Änderung von den Wissensträgern gegenlesen zu lassen. Damit zeigt man auch seine Wertschätzung für die Dokumentation.
Falk Sippach: Da gibt es verschiedene Gründe. Zum einen ist Entwicklerinnen und Entwicklern teilweise nicht klar, was sie in welchem Umfang und in welcher Form dokumentieren sollen. Wenn sie sich außerdem zu wenig Gedanken über die Zielgruppe machen und die Inhalte nicht aktuell halten, wird die Dokumentation nicht gelesen. Und damit sinkt die Motivation, sie zu schreiben. Häufig sind auch andere Themen wichtiger, während der Stellenwert der Dokumentation zu gering ist. Und letztlich sind die typischen Dokumentationswerkzeuge zu weit entfernt vom Arbeitsalltag, sodass die Hürden gerade für die Entwickler unnötig hoch sind.
Gernot Starke: Coding und technische Aufgaben machen halt mehr Spaß. Aber diesen Spaßfaktor mal außer Acht gelassen: Teams bekommen teilweise die unspezifische Aufforderung "Dokumentiert mal was", wobei insbesondere unklar bleibt, was denn genau zu dokumentieren ist und in welchem Tiefgang. Noch schlimmer: Oftmals bleibt die Zielgruppe der Dokumentation ungenannt – und niemand dokumentiert gerne "für die Tonne". Wenn mir als Entwickler oder Entwicklerin klar ist, dass ich eine bestimmte Sache für eine konkrete Person ABC erstelle, habe ich eine viel höhere Motivation, als wenn ich denke, "das liest ja eh niemand".
Ein dritter Grund für die Unbeliebtheit könnte hoher Aufwand und Formalismus sein: Gerade UML- oder SysML-Modellierungswerkzeuge haben meiner Ansicht nach teilweise eine schlechte Usability, sodass Dokumentation damit gegenüber leichtgewichtigen Tools wie draw.io wie ein Albtraum erscheint. Zu guter Letzt macht Dokumentation keinen Spaß, wenn die bisherige schlecht oder veraltet ist oder man im Wiki vor lauter Bäumen den Wald nicht mehr sehen kann.
(Bild: Iltun Huseynli auf Unsplash)
Auf der Online-Konferenz betterCode() ArchDoc am 30. September dreht sich auch alles um moderne und einfache Softwarearchitektur-Dokumentation. Sprecher sind unter anderem die hier interviewten Charlotte Scharbert, Alexander Schwartz und Gernot Starke, während Falk Sippach als Beirat das Programm mitgestaltete.
Noch bis zum 8. September gibt es einen Frühbucherrabatt.
