Wie man eine gute Software-Dokumentation erstellt und pflegt

Einführung

Ein wichtiges und dennoch oft nicht sehr stark beachtetes Thema ist die Dokumentation von Wissen, in der IT insbesondere die Dokumentation von Software. Im nachfolgenden Beitrag konzentrieren wir uns auf die Dokumentation, die von an der Entwicklung beteiligten Personen (Architekten und Entwickler) und Teams erstellt wird. Die Dokumentation rund um Prozesse und Anforderungen lassen wir im Beitrag aussenvor, da es bei der reinen Softwaredokumentation genug zu entdecken gibt.

Häufig stürzen wir uns in ein bestehendes aktives Projekt oder übernehmen die Wartung und den Support von Applikationen, nur um festzustellen, dass die Dokumentation entweder fehlt oder nicht ausreichend ist. Das ist sehr häufig die Erfahrung von Entwicklern. Doch warum ist das meist der Fall? Dafür gibt es so einige Gründe.

• Geschwindigkeit – Speed is key – und die Softwareentwicklung nimmt stetig an Tempo zu. Der Output an Features wird meist übergewichtet, sodass Themen wie Dokumentation als «unwesentlich bzw. vernachlässigbar» erachtet werden und zwangsläufig vernachlässigt werden.

• Komplexität – Anforderungen und Softwarelösungen werden immer komplexer und somit auch die Pflege und das Erstellen der Dokumentation, was zusätzliche Zeit in Anspruch nimmt.

• Darstellung – Diagramme und Zeichnungen von Software Applikationen sind meist nicht sehr anschaulich und die Aktualisierung teils sehr aufwendig, sodass diese meist bei der Weiterentwicklung veralten und nicht immer aktualisiert werden.

• Coden – Entwickler wollen interessante Features und Applikationen umsetzen und konzentrieren ihre Tätigkeiten auch meist darauf. Dokumentation wird als langweilig empfunden, wodurch die Erstellung nicht immer zeitnah erfolgt.  

All diese Punkte tragen dazu bei, dass ein besonderes Augenmerk darauf gelegt werden sollte, dass die Software Dokumentation erstellt und auch kontinuierlich gepflegt wird.

Bei all dem Aufwand und der Zeit, die nötig sind, sollten wir uns fragen: Warum überhaupt die Mühe? Warum ist Softwaredokumentation wichtig? Folgende Punkte veranschaulichen die Relevanz.

• Onboarding von neuen Teammitgliedern: Jedes Mal, wenn ein neuer Entwickler zum Team stößt, hilft eine gute Dokumentation bei der schnellen Orientierung und erfordert keine umfangreiche Zeitinvestition von anderen Teammitgliedern, um ein gutes Grundwissen über das Projekt zu vermitteln.

• Regulatorische Anforderungen und Audits: Wenn die Software, die Sie entwickeln, externen oder internen Audits unterzogen werden muss oder von irgendwelchen regulatorischen Anforderungen beeinflusst wird, dann erleichtert eine gute Dokumentation die Arbeit mit den Auditoren erheblich. Manchmal ist die Dokumentation sogar eine strenge Anforderung für ein Audit.

• Kommunikation mit allen Beteiligten: Eine gute Dokumentation ermöglicht es allen Arten von Stakeholdern, die Software in dem Kontext zu verstehen, der sie interessiert. Wenn die Dokumentation die verschiedenen Arten von Stakeholdern berücksichtigt und die Formulierungen sorgfältig anpasst, um weniger oder mehr technisch zu sein, dann spart das Team viel Zeit, die sonst damit verbracht wird, allen die Eigenschaften des Softwaresystems zu erklären und zu übersetzen.

Eigenschaften der Software-Dokumentation

Eine gute Softwaredokumentation hat folgende Eigenschaften, die es ermöglichen alle Anforderungen der modernen Entwicklungszyklen abzudecken:

• Einfach: Die Dokumentation sollte einfach und minimalistisch sein, um den Pflegeaufwand zu verringern und sicherzustellen, dass alle Beteiligten die Kernaspekte verstehen können.

• Ganzheitlich: Verschiedene Arten von Dokumentationslesern benötigen unterschiedliche Kontexte. Eine gute Dokumentation sollte alle Beteiligten berücksichtigen und sicherstellen, dass jeder mitmachen und verstehen kann.

• Wiederverwendbar: Die Struktur, das Vokabular und das Modell der Software-Dokumentation sollten für neue Software-Projekte wiederverwendbar sein, daher ist ein strukturiertes aber gleichzeitig flexibles Dokumentationsmodell sehr nützlich.

• Automatisiert: Um sicherzustellen, dass die Dokumentation im Laufe der Zeit gepflegt wird und nur minimale Auswirkungen auf die Entwicklungsteams hat, sollten die meisten Diagramme, Tabellen und Spezifikationen so weit wie möglich automatisiert sein.

• Mobil: Es sollte einfach sein, die Dokumentation unabhängig auf einem beliebigen Hosting-Medium zu erstellen und zu verteilen.

• Implementierung: In diesem Abschnitt werden wir uns verschiedene Tools, Frameworks und Dokumentationsmodelle ansehen, um die Anforderungen an die Dokumentationseigenschaften zu erfüllen. Wir werden uns auf spezifische Tools und Standards konzentrieren, die zur Umsetzung unserer Strategie verwendet werden können. Bitte beachten Sie, dass es zu jedem Tool, Framework oder Standard fast immer Alternativen gibt. Wir zeigen ein paar gängige Lösungen zu den jeweiligen Anforderungen.