Technische Dokumentation mit Markdown schreiben — Best Practices
Technische Dokumentation ist für den Erfolg jedes Software-Projekts entscheidend. Schlecht dokumentierte Software führt zu Support-Anfragen, Frustration und Nutzerabwanderung. Markdown ist das Standardformat für technische Docs — es ist einfach zu schreiben, gut versionierbar und von vielen Dokumentationsplattformen unterstützt. Der WikiPlus Markdown-Vorschau-Tool hilft bei der Entwicklung und Überprüfung technischer Dokumentation.
Typen technischer Dokumentation und ihre Anforderungen
Technische Dokumentation ist kein monolithisches Konzept — es gibt verschiedene Typen mit unterschiedlichen Zielen. API-Dokumentation: Beschreibt Endpunkte, Parameter, Antwortformate und Fehler-Codes. Meist strukturiert nach Ressourcentypen. Interaktive Beispiele (Code, der ausgeführt werden kann) sind besonders wertvoll. Nutzerhandbücher: Schritt-für-Schritt-Anleitungen für Endnutzer. Viel Bildmaterial und klare Nummerierung. Einfache Sprache, keine Fachbegriffe ohne Erklärung. Getting-Started-Guides: Führen neue Nutzer in wenigen Schritten zum ersten Erfolg. Kritisch für Aktivierung und Adoption. Referenzdokumentation: Vollständige Auflistung aller Funktionen, Klassen, Methoden. Oft auto-generiert aus Code-Kommentaren (JSDoc, TypeDoc). Troubleshooting-Guides: Bekannte Probleme und ihre Lösungen. FAQ-Format. Jeder Typ hat eigene Anforderungen an Struktur und Detailtiefe — Markdown bietet die Flexibilität für alle.
Diátaxis-Framework: Ein Strukturmodell für Dokumentation
Das Diátaxis-Framework (von Daniele Procida entwickelt) ist ein bewährtes Strukturmodell für technische Dokumentation. Es teilt Dokumentation in vier Typen: Tutorials: Lehrorientiert. Führt den Nutzer durch eine Lernaufgabe. 'Lass uns einen JSON-Formatter bauen'. How-to Guides: Zielorientiert. Beantwortet 'Wie mache ich X'. 'Wie validiere ich JSON mit JavaScript'. Reference: Informationsorientiert. Beschreibt die Funktionsweise. 'JSON-Formatter API Reference'. Explanation: Verständnisorientiert. Erklärt Konzepte und Hintergründe. 'Warum JSON-Validierung wichtig ist'. Jeder Typ hat eine andere Zielgruppe und einen anderen Kontext. Das Framework hilft dabei, Dokumentations-Inhalte dem richtigen Typ zuzuordnen und keine Mischformen zu erstellen, die keinen Typ richtig bedienen. In Markdown: Separate Dateien oder Ordner für jeden Dokumentationstyp sind eine gute Praxis.
Dokumentations-Toolchains: Von Markdown zur Dokumentationswebsite
Markdown-Dateien allein sind kein fertiges Dokumentationsprodukt — sie müssen in eine navigierbare Website oder ein PDF umgewandelt werden. Beliebteste Dokumentationstools: Docusaurus (React, von Meta/Facebook): Sehr beliebt für Open-Source-Projekte. Integriertes Versionierung und Suche. VitePress (Vue-basiert): Schnell, modern, gut für Bibliotheksdokumentation. MkDocs (Python): Einfach zu konfigurieren, beliebt für Python-Projekte. Material for MkDocs als Theme ist sehr populär. Sphinx (Python): Mächtig, aber komplexer. Standard für Python-Paket-Dokumentation. ReadTheDocs: Hosting-Plattform für technische Dokumentation, unterstützt Sphinx und MkDocs. GitHub Pages mit Jekyll: Kostenlos für Open-Source-Projekte, direktes Deployment aus GitHub. Alle diese Tools verwenden Markdown (oder RST bei Sphinx) als Content-Format. Der WikiPlus Markdown-Vorschau-Tool ist ideal für die Content-Entwicklung vor der Integration in diese Systeme.
Dokumentation aktuell halten: Docs-as-Code
Docs-as-Code ist ein Ansatz, bei dem Dokumentation genauso behandelt wird wie Code: mit Versionskontrolle, Code-Reviews und automatisierter Deployment-Pipeline. Kernprinzipien: Dokumentation im selben Repository wie der Code (oder in einem nahen Docs-Repository). Markdown-Dateien werden mit Git verwaltet. Änderungen durchlaufen Pull-Request-Reviews. CI/CD-Pipeline baut und deployt die Dokumentationswebsite automatisch. Vorteile: Dokumentation bleibt synchron mit Code-Änderungen (wenn PRs auch Docs-Updates erfordern). Versionshistorie zeigt, wann und warum Dokumentation geändert wurde. Alle Team-Mitglieder können zur Dokumentation beitragen. Herausforderungen: Technische Hürde für Nicht-Entwickler (Git, Markdown, Pull Requests). Veraltete Dokumentation trotzdem möglich, wenn keine Kultur der Docs-Pflege vorhanden ist. Der WikiPlus Markdown-Vorschau-Tool ist ein einfacher Einstieg in Markdown ohne Toolchain-Setup — ideal für erste Schritte mit Docs-as-Code.
Häufig gestellte Fragen
- Wie dokumentiere ich eine REST API in Markdown?
- Strukturiere die Dokumentation nach Endpunkten. Für jeden Endpunkt: HTTP-Methode, URL, Parameter-Tabelle, Request-Body-Beispiel, Response-Beispiel (beide als JSON Code-Blöcke), mögliche Fehler-Codes. OpenAPI/Swagger ist eine strukturiertere Alternative zu handgeschriebener Markdown-API-Dokumentation.
- Wie halte ich Dokumentation und Code synchron?
- Dokumentation im selben Repository wie Code speichern. PRs sollten Docs-Updates einschließen, wenn sich API oder Verhalten ändert. Definition-of-Done für Features: Akzeptanzkriterium 'Dokumentation aktualisiert'. Automatische API-Dokumentation aus JSDoc/TypeDoc-Kommentaren reduziert Sync-Aufwand für Referenzdokumentation.
- Welche Sprachen unterstützt GitHub Markdown für Syntax-Highlighting?
- GitHub verwendet Linguist für Sprach-Erkennung und unterstützt über 300 Programmiersprachen im Syntax-Highlighting. Die häufigsten: javascript, typescript, python, ruby, go, rust, java, c, cpp, csharp, bash, sql, yaml, json, html, css, markdown. Die vollständige Liste findest du auf github.com/github/linguist.