photo-1494599948593-3dafe8338d71.jpg

News

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:

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.

Einfach

Um die Dokumentation einfach zu halten, brauchen wir ein geeignetes Medium. Die meisten Dokumentationen sind heutzutage entweder in MS Word oder PDF. Für experimentierfreudige gibt es auch Markdown, was für Entwickler einige Vorteile gegenüber den Texteditoren mit sich bringt.  

Der Markdown-Leitfaden: Ein kostenloses und quelloffenes Referenzhandbuch, das erklärt, wie man Markdown verwendet.

Automatisiert

PlantUML ist ein Tool für die Darstellung von Diagrammen. Diagramme in PlantUML folgen der "...as code" Bewegung. Wobei das Diagramm on the fly aus domänenspezifischer Sprache generiert wird. Dies ist sehr nützlich und ermöglicht es, dass alle Online-Dokumentationen, die auf ein zentrales Diagramm-Repository verweisen, automatisch aktualisiert werden.

Um API-Ressourcen (REST) oder -Methoden (RPC) automatisiert zu dokumentieren, können wir Dokumentationsgeneratoren wie Swagger verwenden, die Dokumentation aus Code-Kommentaren oder aus API Spec generieren.

Swagger nimmt die manuelle Arbeit aus der API-Dokumentation heraus, mit einer Reihe von Lösungen zur Generierung, Visualisierung und dem Teilen.

Schließlich sollte die Dokumentation für ein bestimmtes Software-Projekt in einem eigenen Repository gekapselt werden, die zum selben Software-Projekt gehören. Teil der CI/CD-Pipeline sollte die automatisierte Erstellung und Bereitstellung der Dokumentationsartefakte sein. Wenn Sie so viel wie möglich automatisieren, stellen Sie sicher, dass die Dokumentation im Laufe der Zeit gepflegt wird.

Wiederverwendbar

Um die Dokumentation wiederverwendbar zu machen, müssen wir uns auf Standards und Best Practices einigen, an die sich alle Software-Projekte halten sollen.

Hier sind einige Standards und Modelle, die wir bei der Definition des Dokumentationsrahmens hilfreich finden:

arc42 ist eine Vorlage für die Kommunikation und Dokumentation. Es schafft ein Gerüst und eine Struktur, die hilft, Themen in den richtigen Kontext zu stellen und verschiedene Stakeholder angemessen anzusprechen.

Das C4-Modell hilft bei der Strukturierung von Diagrammen und visuellen Artefakten für die Software-Dokumentation. Es passt sehr gut zum arc42-Ansatz. Eine Person repräsentiert einen der menschlichen Nutzer Ihres Softwaresystems (z.B. Akteure, Rollen, Personas, etc.).

Zusammenfassung

Das folgende Diagramm zeigt, wie ein zentralisiertes Dokumentations-Repository pro Produkt oder Projekt verwendet werden könnte, um Software-Dokumentation zu pflegen, die Dateien aus verschiedenen Repositories enthält und die Software zusammensetzt (z. B. bei einer Microservices-Architektur).

Software-Dokumentation ist sehr wichtig aber ihre Erstellung und Pflege kann anspruchsvoll sein. In diesem Beitrag haben wir anhand der Eigenschaften (Einfach, ganzheitlich, automatisiert, wiederverwendbar und mobil) aufgezeigt, was eine gute Dokumentation ausmacht.

Zusätzlich haben wir uns ein paar Tools vorgestellt, die uns bei der Erstellung, Pflege und Veröffentlichung von Software-Dokumentation unterstützen. Bei Fragen und Feedback stehen wir gerne zur Verfügung.

Einfach

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

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.

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.

Mobil

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

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

Unsere bisherige Dokumentation basiert auf offenen Standards, nutzt Open Source flexible und leistungsfähige Werkzeuge. Jetzt ist es an der Zeit, sie für alle Beteiligten verfügbar zu machen.

Um die Dokumentation portabel zu machen, müssen wir in der Lage sein, sie auf Basis unserer Markdown-Dateien zu generieren und in einer leicht konsumierbaren Form zu präsentieren. Der beste Weg, dies zu tun, ist die Bereitstellung der Dokumentation als Webseite, basierend auf statischen Dateien oder HTML, die on the fly generiert werden.

Docsify ist für die Bereitstellung von Dokumentation, die aus Markdown-Dateien in HTML umgewandelt werden, bestens geeignet und basierend auf ein paar einfachen Konfigurationsdateien.

Kontaktieren Sie uns für weitere Informationen

Unser Team hilft Ihnen gerne weiter.

Hauptsitz Wiesenstrasse 5,

8952 Schlieren

+41 (0) 44 745 17 77

Niederlassung Indien 14th floor,

SKAV 909, Bengaluru

+91 988 0236 808

Niederlassung Kosovo Vicianium Nr. 251, Arberi, Pristina

  • Facebook
  • Twitter
  • LinkedIn - Grey Circle

© 2020 Comitas AG. All rights reserved.