Richtig dokumentieren

Autor: Gerd Raudenbusch
Stand: 27.05.2026

Motivation

Dokumentation ist für moderne Teams und Projekte von entscheidender Bedeutung, da sie Wissen festhält, die Zusammenarbeit fördert und die Effizienz über mündliche Überlieferungen hinaus steigert.

Die Externalisierung von Wissen befreit den Einzelnen

Es lohnt sich, Informationen außerhalb des eigenen Kopfes zu speichern („Was nicht im Kopf ist, bedreit Dein Denken“), denn es verhindert persönliche Wissenssilos und undurchsichtige Abhängigkeiten von Schlüsselpersonen. Das Fachwissen einer einzelnen Person wird schnell zum Engpass, und so ermöglicht gute Dokumentation es, sich auf Innovation zu konzentrieren, anstatt auf das Abrufen oder Erklären von Informationen. Undurchsichtige Prozesse ohne Dokumentation verursachen ständigen geistigen Aufwand, während eine klare gemeinsame Dokumentation eine schnelle Einarbeitung ermöglicht.

Teilen stärkt das Team

Wissen für sich zu behalten ist wie das „Trainieren von Muskeln“ im Alleingang: zwar ein persönliches Wachstum, doch das Teilen durch Dokumentation bringt das gesamte Team voran. Es vervielfacht die Produktivität, da andere dazu Beiträge leisten, Fehler beheben und die Arbeit weiterentwickeln, ohne Lösungen neu erfinden zu müssen. Gut dokumentierte Projekte beschleunigen die Entwicklung, reduzieren Besprechungen und bauen kollektive Kompetenz auf, wodurch individuelle Anstrengungen zu einer Stärke des Teams werden.

Effizienz statt mündlicher Überlieferung

Im Gegensatz zu den Stämmen der Antike, die ihre Geschichte am Lagerfeuer besangen, ersetzt moderne Dokumentation die ineffiziente mündliche Weitergabe durch skalierbare, durchsuchbare Aufzeichnungen. Das schriftliche Festhalten bewahrt den Kontext dauerhaft, unterstützt asynchrones Arbeiten über Zeitzonen hinweg und entwickelt sich mit jeder neuen Version weiter. Das ist weitaus effizienter als mündliche Erzählungen, die verblassen, wiederholt oder gar neu erarbeitet werden müssen. Dieser Wandel ermöglicht ein schnelleres Wachstum ohne einen proportionalen Anstieg des Kommunikationsaufwands.

„Demut bedeutet nicht, sich anderen unterlegen zu fühlen, sondern sich von der Anmaßung der eigenen Wichtigkeit zu befreien.“

(Matthieu Ricard, buddhistischer Mönch und Molekularbiologe)

Die Hürden bei der Dokumentation liegen nicht nur in ihrer Erstellung, sondern auch in ihrer Lesbarkeit. Angesichts unterschiedlicher Systeme und Formate (Git-Wiki, Dokuwiki, Websites, PDFs, Word-Dokumente) scheint es zunächst schwierig, ihrem Umfang gerecht zu werden. Das entmutigt viele, die vor dieser Herausforderung stehen. Dieser Artikel soll anspornen, diese Herausforderung anzunehmen.

Interoperable Bilder und Diagramme

Interoperable Dokumentation umfasst auch Diagramme und Bilder: Dia, LibreOffice Draw oder draw.io sind proprietäre Grafikprogramme, die häufig zur Erstellung von Diagrammen verwendet werden. Allerdings sind generische Formate besser geeignet, da ihre Vorteile in deutlich kleineren Dateigrößen und der Möglichkeit zur Bearbeitung liegen. Zudem lassen sie sich auf die gleiche Weise mit dem Tool ffmpeg in gängige Formate (jpg, gif, png, webm) konvertieren.

Scalable Vector Graphics (SVG)

Das Scalable Vector Graphics-Format svg ist ein XML-basiertes Format zur Beschreibung zweidimensionaler Vektorgrafiken, die sich ohne Qualitätsverlust skalieren lassen. Der Hauptvorteil von SVG gegenüber anderen Bildformaten besteht also darin, dass es auf jede beliebige Größe skaliert werden kann, ohne unscharf oder pixelig zu werden. Es wird häufig für Webgrafiken, Diagramme und Exporte verwendet. Inkscape ist ein kostenloses, natives Tool zum Erstellen und Bearbeiten solcher Vektorgrafiken, aber auch LibreOffice Draw kann SVG exportieren, wenn die entsprechenden Elemente zuvor markiert worden sind.

GraphML

GraphML ist ein XML-basiertes, offenes Standarddateiformat zum Speichern und Austauschen von Graphen-Daten, einschließlich Knoten, Kanten und deren Eigenschaften. Es ist dem SVG-Format für graphspezifische Aufgaben überlegen, da es strukturierte Daten wie Knoten, Kanten und Attribute explizit kodiert, anstatt nur die visuelle Darstellung zu übernehmen, und Graphen als XML mit klaren Hierarchien für Knoten, Verbindungen und Metadaten speichert, was wiederum Algorithmen für Analyse, Layout oder Abfragen ermöglicht. SVG rendert beliebige Formen immer nur ohne Graphsemantik, sodass Tools zusätzliche Eigenschaften wie z.B. Konnektivität oder kürzeste Wege nicht zuverlässig berechnen können. Mit yEd online oder yEd als kostenlose, plattformübergreifende Diagrammanwendung können Sie komplexe Flussdiagramme, Netzwerkdiagramme, UML, BPMN und andere Visualisierungen erstellen, diese als SVG exportieren und als GraphML speichern.

Interoperabler Text

Es gibt viele Systeme, Markupsprachen und Möglichkeiten, seine Texte zu verfassen und zu strukturieren, sodass die Wahl zunächst schwer erscheint.

Warum nicht...?

• LaTeX: Nur lange wissenschaftliche Texte wie Abschlussarbeiten, Dissertationen und Forschungsarbeiten mit Kapiteln, Abbildungen, Tabellen und Querverweisen profitieren von der starken Struktur und Automatisierung von LaTeX. Dokumente mit vielen Formeln oder anspruchsvoller Typografie (gute Silbentrennung, feine Steuerung der Abstände, hochwertige Druckausgabe) lassen sich erfahrungsgemäß mit LaTeX viel besser bearbeiten. Wenn eine Universität, eine Zeitschrift oder eine Konferenz eine offizielle Vorlage in LaTeX bereitstellt oder einen bestimmten Zitierstil vorschreibt, ist LaTeX in der Regel die praktischste oder sogar notwendige Wahl. Für kurze Texte, Blogbeiträge, README-Dateien und die meisten Entwicklerdokumentationen ist Markdown jedoch einfacher, schneller zu erlernen und als reiner Text sehr gut lesbar. Markdown besticht fast alle anderen Beschreibungssprachen mit der Minimalität seiner syntaktischen Steuerelemente.

• AsciiDoc: Markdown hat derzeit eine weitaus größere Verbreitung als AsciiDoc. Dies zeigt sich daran, wie viele Plattformen, Tools und Gemeinschaften Markdown als ihr standardmäßiges, schlankes Markup-Format verwenden. Markdown ist in viele wichtige Plattformen integriert, wie beispielsweise Git-Hosting-Dienste, Wikis, Editoren und Dokumentationsseiten, wo es als Defacto-Standard behandelt wird. AsciiDoc wird hauptsächlich in Kreisen der technischen Dokumentation verwendet (zum Beispiel im Umfeld einiger Unternehmens- und Open-Source-Projekte), ist aber insgesamt weniger präsent und hat eine kleinere Nutzerbasis. Wenn „maximale Reichweite“ und „funktioniert standardmäßig fast überall“ die Hauptkriterien sind, liegt Markdown eindeutig vorn.

• Word: Microsoft Word kann teuer, ressourcenintensiv und übermäßig komplex sein, und sein binäres Dateiformat erschwert die Versionskontrolle, die Zusammenarbeit in Entwickler-Workflows und die langfristige Kompatibilität im Vergleich zu einfachen Textformaten wie Markdown. Darüberhinaus befängt der Konzern Microsoft seine Kunden in Produken und Lizenzen mit immer fragwürdigeren Ideen, welche nicht nur proprietär, sondern auch zunehnend enteignendenden Einfluss auf die Datenhoheit und Privatsphäre des Anwenders nehmen.

• LibreOffice Writer: LibreOffice ist eine ebenbürtige Alternative zu Word, mit der sich ganze Bücher professionell verfassen lassen. Doch verwendet Libreoffice, genau wie Word, komplexe Binär-/ODF-Dateien und eine schwerfällige Benutzeroberfläche. Das Datenformat macht in Versionskontrollsystemen den Vergleich und die Pflege von Texten schwierig, im Vergleich zu Markdowns einfachem, schlankem Klartextformat, welches sich mit Vergleichstools wie diff, meld oder anderen leicht bearbeiten lässt.

• PDF: ist lediglich ein für den Drucker optimiertes Format mit festem Layout, welches im Vergleich zum flexiblen Klartextformat von Markdown die Zusammenarbeit Versionskontrolle, Wiederverwendung von Inhalten und ein responsives Design erschwert. PDF-Editoren mildern zwar einige Einschränkungen bei der PDF-Bearbeitung, indem sie Anmerkungen, Textänderungen und das Ausfüllen von Formularen ermöglichen, doch sie bleiben im Vergleich zu Markdowns nativer textbasierter Bearbeitung und Versionskontrolle umständlich, proprietär und weniger effizient für kollaborative oder iterative Arbeitsabläufe.

• Confluence: Zu den Nachteilen von Confluence im Vergleich zu Markdown zählen eine höhere Komplexität und Lernkurve, die Abhängigkeit von einer proprietären Web-Benutzeroberfläche, eine geringere Eignung für Git-basierte Workflows sowie eine sehr eingeschränkte, wenig native Markdown-Unterstützung, was die Bearbeitung, Versionierung und Wiederverwendung von Inhalten über verschiedene Tools hinweg viel komplizierter macht als bei Markdown-Dateien im Klartextformat.

• DokuWiki: Die Nachteile klassischer Wiki-Sprachen (wie DokuWiki und MediaWiki) sind höhere Komplexität, mehr Dialekte mit enger Bindung an eine bestimmte Wiki-Engine, sowie geringere Portabilität auf andere Tools und Formate als das weit verbreitete, editorunabhängige Klartextformat von Markdown. ​

Konvertierung von Textformaten

Glücklicherweise bietet das Tool Pandoc die Möglichkeit, zwischen diesen Formaten zu konvertieren. Am effektivsten ist es jedoch, die Dokumentation direkt in der Beschreibungssprache Markdown zu verfassen und sie anschließend in Dokuwiki, HTML, PDF oder Word zu konvertieren. Zusammen mit Pandoc ist Markdown effektiv der einzige praktische gemeinsame Nenner all dieser Systeme; es gibt keine andere universelle minimale Schnittmenge, welche all diese Systeme vollständig miteinander teilen (abgesehen von einer sehr kleinen Teilmenge wie reinen Text, einfache Überschriften, Listen und Links, die für echte Projekte in der Regel zu begrenzt ist). Weiterhin wird Markdown auch am öftesten von KI-Suchmaschinen als Exportsprache angeboten.

Markdown

Markdown ist die wohl einfachste Auszeichnungssprache, mit der sich reiner Text schnell und übersichtlich formatieren lässt, z. B. für Überschriften, Listen, Links oder Hervorhebungen. Dateien im Markdown-Format haben in der Regel die Endung .md und lassen sich leicht in andere Formate wie HTML oder PDF konvertieren.

Pandoc

Pandoc wird oft als „universeller Dokumentkonverter“ bezeichnet, da es Text aus Markdown in PDF, HTML, Word (docx), LaTeX, EPUB und viele andere Formate konvertieren kann. Das Programm ist Open Source, unter der GPL lizenziert und für Linux, Windows und macOS verfügbar.

Pandoc wird meist über die Befehlszeile aufgerufen, beispielsweise um eine Eingabedatei in ein Zielformat zu konvertieren, wobei zahlreiche Optionen (Vorlagen, Filter, Metadaten usw.) zur Verfügung stehen. Intern basiert es auf einer erweiterten Markdown-Variante und einer Zwischendarstellung, die es zur Übersetzung von Inhalten zwischen den verschiedenen Formaten verwendet.

Obsidian

Obsidian ist einer der geeignetsten Markdown-Editoren, da er auf fast allen Plattformen verfügbar ist. Mit Obsidian können Markdown-Notizen durch bidirektionale Verlinkungen miteinander vernetzt und so eine persönliche Wissensbasis ähnlich einem Wikipedia erstellt werden. Die größte Stärke liegt in den lokalen Markdown-Dateien, die zukunftssicher sind und von jedem beliebigen Texteditor gelesen werden können. Obsidian lässt sich durch zahlreiche Plugins und Themes aus der Community individuell anpassen und wächst mit den Bedürfnissen des Anwenders. Die Software ist besonders schnell, da alle Daten lokal gespeichert sind und Cloud-Synchronisation nur optional ist. Für die private Nutzung ist Obsidian komplett kostenlos, nur offizielle Sync- und Publish-Dienste sind kostenpflichtig.

Weiterführende Quellen

• "Die Doku schreiben wir später" - Vortrag von synx auf der fsck 2026 des CCC

• "Your Thoughts in a Graph: Structured Notetaking mit Obsidian" - Vortrag von Leon Amtmann auf der fsck 2025 des CCC