Schwere Voraussetzungen
Die Idee zur Optimierung des Dokumentierens entstand inmitten der Hektik der Aufgabenbearbeitung. Häufige Wechsel zwischen Pipelines, Monitoring, Automatisierung, RnD, Support und detaillierten Zeitbuchungen ließen keine Konzentration auf die Dokumentation zu.
Historie protokollieren
Ich musste meine Aktionen protokollieren, Texte mit Bildern, Links und Zeitstempeln ergänzen und sicherstellen, dass Themen in einem einzigen Rohdokument nicht überschneiden. Es musste so gemacht werden, dass man später leicht den Arbeitsverlauf nachvollziehen konnte.
Mehrfach half das Protokollieren von Putty/Bash, eine verwirrende Arbeitsfolge auf dem Produktivsystem wiederherzustellen. Nutzen Sie diese Möglichkeit nicht.
Veröffentlichung
Später wollte ich den Rohdokumenten einen endgültigen Dokumentstatus verleihen und ihn in der Projekt-Dokumentation veröffentlichen. Am Ende gelang es, deutlich über die Grenzen hinauszugehen.
Ziel war es, Rohdokumente mit erweitertem Formatierungsansatz zu erstellen und mit der Dokumentation wie mit Code zu arbeiten.
Dies sparte Zeit für Formatierung und Umwandlung in den Standardveröffentlichungsformat.
Online-Format
Schließlich ermöglichte das Format Markdown+Git die automatische Generierung von Online-Dokumentation. Als Bonus kam der Offline-Modus, der über den Browser-Cache verfügbar war. In geschlossenen Netzwerken des Kunden, im Flugzeug oder an Orten ohne Internet war dieser Modus sehr nützlich. Auch die Kunden schätzten ihn.
Markdown-Format wird von Gitlab, YouTrack, einigen Messenger-Apps unterstützt und von allen LLM-Modellen erkannt.
Gemeinsame Rohdokumente
Wenn Ihre Arbeit nicht mit Finanzen verbunden ist, sollten Ihre Rohdokumente nicht versteckt sein. Im Gegenteil, erlauben Sie gemeinsames Arbeiten daran.
Meine Bemühungen, Rohdokumente öffentlich zugänglich zu machen, führten zur Entwicklung von „Dokumentation als Code“. Die DevOps-Team wurde von anonymen Textdateien und der Suche nach „Wo wurde das aufgeschrieben?“ befreit. Hier gibt es keine Probleme mit verschiedenen Word-Versionen, verschwundenen Bildern oder ähnlichen Dingen. Außerdem wird aus dem Rohdokument sofort eine Online-Version und ein schöner, strenger PDF-Export generiert.
Dokumentation heute
- wird im Markdown-Format verfasst (Editor Typora oder ähnliche mit automatischem Speichern + Commits in IDEA/PyCharm)
- wird in Gitlab gespeichert (für alle Mitarbeiter nach Rollenmodell zugänglich, unterstützt mehrbenutzerspezifisches Bearbeiten)
- wird automatisch in eine Online-Version im Container Docsify zusammengefasst (aktualisiert der Code jede Minute); Websites werden über DNS ins Internet weitergeleitet
- lässt sich leicht in PDF exportieren mit identischem Design, sowohl für die Website als auch für die Datei (Vue.js)
- Diagramme werden im Format Drawio (Outline) und Mermaid (Inline) erstellt
- Diagramme werden in SVG (und gelegentlich in PNG für inkompatible Plattformen) exportiert und enthalten den integrierten Quellcode
Was fehlt noch?Für die meisten Benutzer ist es irrelevant, ob die Dokumentation an einem einzigen Ort gespeichert ist und dort auch im Mehrbenutzermodus bearbeitet werden kann. Es gibt nur wenige Dokumentationsbearbeiter (Contributors), aber viele einfache Benutzer. Für diese ist es wichtig, schnell den richtigen Dokumenteninhalt in der aktuellen Version zu finden und ihn leicht zu teilen. Daraus ergeben sich einige Fragen, wie etwa:
- Wie kann eine automatische Liste der Dokumentation erstellt werden?
- Wie kann die Reihenfolge der Links im Text nach Aktualität der Dokumente sortiert werden (nicht im Sinne von „neuesten Änderungen“, sondern nach inhaltlich relevanten Änderungen – denn niemand interessiert sich für Dokumente, die nur wegen kosmetischen Änderungen an der Spitze der Liste stehen)?
- Wie kann ein Modus für kleine Änderungen direkt im Dokument ermöglicht werden, ohne dass der Benutzer mit den Quelldateien arbeiten muss?
- Wie kann die Dokumentation „in Bündeln“ aktualisiert werden, wenn bestimmte Teile miteinander verknüpft sind und teilweise oder vollständig wiederverwendet werden?
- Wie kann die Dokumentation automatisch generiert werden, da sie sehr schnell veraltet wird?
- Wie kann nicht nur die Dokumentation selbst, sondern auch die Notwendigkeit, zugehörige Kommentare von Mitarbeitern in öffentlichen Kanälen oder Communities zu aktualisieren oder zu ergänzen, berücksichtigt werden? Denn hier bildet sich oft das Urteil über die Autorität (die Worte einer Person, die mit der Dokumentation in Verbindung steht, sind wichtiger als die Dokumentation selbst – ein etablierter Fakt).
Der dritte Punkt findet sich bereits auf einigen Plattformen, beispielsweise Discourse. Und KI kann dabei helfen, strukturierte Dokumentation zu erreichen.