Documentation as Code: Struktur

Dokumentation kann für viele Entwickler frustrierend sein. Veraltete oder schlecht strukturierte Dokumente machen es schwer, benötigte Informationen schnell zu finden oder selbst zu erstellen. Besonders in einem sich ständig weiterentwickelnden technologischen Umfeld ist eine gut organisierte Dokumentation von großem Wert, auch wenn Tools wie ChatGPT die Generierung von Inhalten vereinfachen. Dabei liegt der Fokus oft nur auf dem, was gemacht wurde; Informationen über das Wie und die Entscheidungen, die zu diesen Schritten führten, werden häufig vernachlässigt. Die Dokumentation dieser Entscheidungen ist jedoch besonders wichtig, gerade wenn du historisch auf dein Projekt zurückblickst oder auch neue Leute ins Projekt kommen. Und Hand aufs Herz: Eine automatisch generierte Hilfedatei, beispielsweise mit dem Sandcastle Helpfile Builder aus XML-Kommentaren im Code, ist noch lange kein gutes Handbuch – geschweige denn eine wirklich hilfreiche Dokumentation.

Aufbewahrung und Struktur

Eine sinnvolle Methode ist die Ablage der Dokumentation nah am Code. So kannst du Inhalte jederzeit aktualisieren, ohne auf separate, oft schwer zugängliche Dokumente zurückgreifen zu müssen. Documentation as Code ist dabei ein bewährter Ansatz, bei dem Dokumentationen in Markdown innerhalb der Versionsverwaltung gespeichert werden. Diese Methode unterstützt die Nachvollziehbarkeit von Änderungen und ermöglicht einen strukturierten Review-Prozess. Zudem ist Markdown leicht zu handhaben und lässt sich problemlos in andere Formate umwandeln. Hier können Tools wie Docusaurus oder MkDocs helfen, um deine Markdown-Dokumente in ansprechende Websites zu verwandeln, die für verschiedene Zielgruppen zugänglich sind.

Dokumentationsvorlagen

Dokumentationsvorlagen bieten eine strukturierte Grundlage, um konsistente und umfassende Dokumentationen zu erstellen. Beispiele wie arc42 für Softwarearchitekturen oder das Diátaxis-Framework für technische Dokumentationen helfen dabei, Inhalte klar zu gliedern und auf die Zielgruppe abzustimmen. Solche Vorlagen fördern die Wiederverwendbarkeit und erleichtern die Zusammenarbeit im Team. Bevor du das Rad neu erfindest, lohnt es sich, bestehende Lösungen zu prüfen. Open-Source-Projekte bieten oft wertvolle Einblicke und bewährte Ansätze, die du für deine eigene Dokumentation adaptieren kannst.

Typen der Dokumentation

Eine klare Gliederung der Dokumentation ist essenziell. Es gibt verschiedene Dokumentationstypen, die du berücksichtigen solltest, darunter technische Leitfäden für Entwickler, UI/UX-Richtlinien und Endbenutzerdokumentationen. Dabei ist es hilfreich, ein zentrales Dokumentationsverzeichnis zu erstellen. Ein Beispiel für eine Ordnerstruktur könnte folgendermaßen aussehen:

📂 docs/
├── 📁 .attachments/
├── 📁 development/
├── 📁 architecture/
├── 📁 domain/
├── 📁 user/
├── 📁 operations/

• .attachments/: Hier werden alle zusätzlichen Dateien wie Bilder, Diagramme oder andere Anhänge abgelegt, die in der Dokumentation verwendet werden.
• development/: Dieser Ordner enthält Dokumentationen zu Entwicklungsprozessen, Coding-Guidelines, API-Beschreibungen und technischen Implementierungsdetails.
• architecture/: In diesem Ordner werden Architekturentscheidungen, Diagramme, technische Übersichten und Design-Dokumente gespeichert.
• domain/: Hier werden Informationen zur fachlichen Domäne abgelegt, wie z. B. Glossare, Geschäftsregeln oder Modelle.
• user/: Dieser Ordner enthält Dokumentationen für Endbenutzer, wie Benutzerhandbücher, Tutorials oder FAQs.
• operations/: In diesem Ordner werden Betriebsdokumentationen wie Deployment-Anleitungen, Monitoring-Strategien und Incident-Response-Pläne abgelegt.

Jede dieser Kategorien richtet sich an eine spezifische Zielgruppe. Mithilfe von Tools wie Docusaurus oder GitBook können diese Dokumentationen auch separat gehostet werden, um den jeweiligen Bedürfnissen der Nutzer gerecht zu werden. Diese Plattformen bieten benutzerfreundliche Oberflächen und ermöglichen es, Inhalte ansprechend und leicht zugänglich zu präsentieren.

The Seven-Action Documentation Model

Der Artikel The Seven-Action Documentation Model von Fabrizio Ferri-Benedetti stellt ein Modell vor, das technische Dokumentation als Produkt betrachtet, das spezifische Nutzerbedürfnisse erfüllen soll. Anstatt sich ausschließlich auf Dokumenttypen oder Tools zu konzentrieren, richtet dieses Modell den Fokus auf die Aktionen, die Nutzer durch Dokumentation ausführen möchten:

• Appraise (Bewerten) – Herausfinden, ob ein Produkt oder eine Funktion relevant ist.
• Understand (Verstehen) – Konzepte und Zusammenhänge erfassen.
• Explore (Erkunden) – Möglichkeiten und Optionen entdecken.
• Practice (Üben) – Fähigkeiten durch Übungen oder Tutorials entwickeln.
• Remember (Erinnern) – Schnell auf bekannte Informationen zugreifen.
• Develop (Entwickeln) – Eigene Lösungen oder Erweiterungen erstellen.
• Troubleshoot (Fehler beheben) – Probleme identifizieren und lösen.

Es kann in die Dokumentationsstruktur integriert werden, indem die Ordner und Inhalte gezielt auf diese Nutzeraktionen ausgerichtet werden. Beispielsweise könnten spezifische Ordner wie docs/user/troubleshooting oder docs/development/practice erstellt werden, um die jeweiligen Aktionen direkt zu unterstützen. Dies sorgt für eine klare Orientierung und erhöht die Effizienz bei der Nutzung der Dokumentation.

Weitere Strukturierung

Um die Dokumentation noch spezifischer zu gestalten, kann eine zusätzliche Ebene innerhalb der bestehenden Ordnerstruktur eingeführt werden. Dabei sollte darauf geachtet werden, dass die Anzahl der Ordner pro Ebene sieben nicht überschreitet. Dieses Prinzip basiert auf der psychologischen Erkenntnis, dass Menschen Informationen besser verarbeiten können, wenn sie in Gruppen von maximal sieben Elementen organisiert sind. Das sogenannte “Magical Number Seven”-Prinzip trägt dazu bei, die Übersichtlichkeit zu bewahren und die Navigation zu erleichtern.

Natürlich gibt es Ausnahmen, bei denen es sinnvoll sein kann, mehr als sieben Elemente zu verwenden, insbesondere bei komplexen Themen. In solchen Fällen empfiehlt es sich aber, die Inhalte weiter zu unterteilen, zusätzliche Unterordner zu erstellen oder verwandte Themen zu gruppieren. Alternativ können Index-Dateien oder Tags genutzt werden, um die Inhalte besser auffindbar zu machen. Dies trägt zu einer klareren Struktur bei und ermöglicht es den Nutzern, schneller auf die gewünschten Informationen zuzugreifen. Eine gut durchdachte Navigation ist dabei entscheidend, um die Benutzerfreundlichkeit der Dokumentation zu verbessern und den Zugang zu relevanten Inhalten zu erleichtern.

Ein Beispiel für eine detailliertere Struktur, die das Seven-Action-Model berücksichtigt, könnte wie folgt aussehen:

📂 docs/
├── 📁 .attachments/
├── 📁 development/
│   ├── 📁 guidelines/
│   ├── 📁 coding-standards/
│   ├── 📁 troubleshooting/
│   ├── 📁 how-to/
├── 📁 architecture/
│   ├── 📁 introduction/
│   ├── 📁 context/
│   ├── 📁 views/
│   ├── 📁 decisions/
│   ├── 📁 quality/
├── 📁 domain/
│   ├── 📁 glossary/
│   ├── 📁 business-rules/
│   ├── 📁 models/
├── 📁 user/
│   ├── 📁 tutorials/
│   ├── 📁 faqs/
│   ├── 📁 troubleshooting/
├── 📁 operations/
│   ├── 📁 deployment/
│   ├── 📁 monitoring/
│   ├── 📁 post-mortem/

Diese detaillierte Struktur ermöglicht es, die Dokumentation gezielt auf die Bedürfnisse der Nutzer auszurichten und gleichzeitig eine klare Orientierung zu gewährleisten.

Es ist ebenso wichtig, die Struktur der Dokumentation selbst zu dokumentieren. Eine klare Beschreibung, welche Inhalte in welchen Ordnern oder Dateien abgelegt werden sollen, hilft Entwicklern, schnell zu verstehen, wo spezifische Informationen zu finden oder hinzuzufügen sind. Dies reduziert Verwirrung und sorgt für Konsistenz im gesamten Projekt. Eine solche Übersicht kann direkt im Repository abgelegt werden, z. B. in einer Datei wie docs/README.md, um sie leicht zugänglich zu machen.

Auch ist Dokumentation ein lebendiges Konstrukt, das sich mit dem Projekt weiterentwickelt. Es ist wichtig, regelmäßig zu überprüfen, ob die Struktur noch sinnvoll ist oder auch Dokumente im Zweifel umsortiert oder umgruppiert werden müssen. Das kann als dedizierte Anforderung, als wiederkehrende Aufgabe oder auch als Teil des Code-Reviews geschehen. So bleibt die Dokumentation immer aktuell und relevant.

Der Weg zur besseren Dokumentation

Eine durchdachte Ablage und klare Struktur der Dokumentation erleichtern nicht nur die Erstellung, sie steigern auch den Nutzen für alle, die mit dem Code arbeiten. Durch die Wahl der richtigen Methoden kannst du deinen Arbeitsalltag erheblich vereinfachen.

Ein Beispiel kannst du dem Lunaris Playbook entnehmen.

Wie strukturierst du die Dokumentation in deinem Projekt? Schau gerne bei uns auf LinkedIn vorbei und diskutiere mit.