Beginnen Sie mit dem Problem, nicht mit Git
Docs-as-Code wird oft als Werkzeugliste verkauft: Markdown, Git, Pull Request, CI und Static-Site-Generator. Dadurch diskutiert das Team über Editoren, bevor klar ist, welches Dokumentationsproblem überhaupt gelöst werden soll. Typische Probleme sind veraltete Seiten, langsames Review, inkonsistente Terminologie, kaputte Links oder eine Veröffentlichung, die von einer Person abhängt.
Der Ansatz ist nur dann sinnvoll, wenn diese Reibung kleiner wird.
Was Docs-as-Code tatsächlich umfasst
| Phase | Was passiert | Einfach | Reifer |
|---|---|---|---|
| Quelle | Inhalt ändern | Markdown/AsciiDoc in Git | strukturierter Inhalt + Metadatenschema |
| Bearbeitung | Autor arbeitet | GitHub-Webeditor | github.dev, VS Code, IDE oder Authoring UI |
| Preview | künftige Seite sehen | lokaler/Web-Build | Preview pro Änderung |
| Checks | Routinefehler finden | Links + Build | Stil, Begriffe, API, Accessibility, Locales |
| Review | Bedeutung prüfen | ein Reviewer | SME + Redaktion |
| Veröffentlichung | Site aktualisieren | manuell | CI/CD nach erfolgreichen Checks |
Nicht jede Phase braucht maximale Komplexität. Wählen Sie das kleinste Niveau, das das reale Risiko abdeckt.
Textformat heißt nicht IDE-Pflicht
GitHub erlaubt das direkte Bearbeiten einer Datei im Browser. Für längere Änderungen bietet github.dev Suche, Syntaxhervorhebung und Source Control ohne lokalen Clone. Ein SME, der einmal im Monat eine Zahl korrigiert, muss deshalb weder Terminal noch Rebase lernen.
| Rolle | Meist ausreichend | Nicht ohne Grund verlangen |
|---|---|---|
| Technical Writer | github.dev, VS Code oder Lieblingseditor |
bestimmte IDE |
| Gelegentlicher SME | Webeditor + Preview | Terminal, Rebase, lokaler Build |
| Entwickler | IDE + Git | separate CMS, wenn Markdown bequemer ist |
| Redaktion | Browser/Authoring UI | Pipeline-Interna |
Speicherformat und Autorenoberfläche sind zwei verschiedene Entscheidungen.
Ein praxistauglicher End-to-End-Prozess
Produktänderung → Entwurf → Preview → automatische Checks → technisches Review → redaktionelles Review → Merge → Veröffentlichung → Produktionskontrolle.
In kleinen Teams kann eine Person mehrere Rollen übernehmen. Ein Pull Request ist kein Ritual. In größeren Teams sollte der SME Fakten verifizieren, während Technical Writing Struktur, Nutzeraufgabe, Terminologie und Verständlichkeit verantwortet.
Welche Checks sich automatisieren lassen
| Check | Findet | Gute Fehlermeldung |
|---|---|---|
| Build | Syntax, Includes, Templates | Datei + konkrete Ursache |
| Interne Links | entfernte Seiten/Anchors | Quelle + Ziel |
| Metadaten | title, owner, locale, revision | fehlerhaftes Feld |
| Heading-Struktur | falsche Hierarchie | betroffene Überschrift |
| Terminologie | veraltete Begriffe | Begriff + Ersatz |
| Style lint | definierte Muster | kurze Handlungsempfehlung |
| Codebeispiele | Syntax/Format | Beispiel + Fehler |
| API-Vertrag | Abweichung von Schema/OpenAPI | Feld/Endpoint |
| Bilder | Asset, Alt-Text, Größe | Datei + Problem |
| Locales | fehlende Sprache/Revision | Artikel + Sprache |
| Secrets | Token/Schlüssel | Fundtyp ohne Secret im Log |
Ein Warning, das niemand beheben will, ist kein Qualitätsmerkmal, sondern Rauschen.
Wie viel Zeit kann das sparen?
Für Docs-as-Code gibt es keinen seriösen universellen Prozentsatz. Rechnen Sie mit sichtbaren Annahmen. Bei 40 Änderungen pro Monat und 20 Minuten manueller Routine pro Änderung entstehen 13 h 20 min aktive Arbeit. Nach Automatisierung und etwa 2 Minuten Ergebnisprüfung pro Änderung bleiben ungefähr 1 h 20 min.
Annahme: 40 × 20 Minuten gegenüber 40 × 2 Minuten. Planungsmodell, kein Branchenbenchmark.
Forschung zu industriellem Code Review zeigt, dass automatisierte Routinearbeit messbar entlasten kann; konkrete Prozentwerte aus Softwareentwicklung dürfen aber nicht einfach auf Dokumentation übertragen werden.
Messen Sie den eigenen Effekt statt eine Studie zu erfinden
TechWriters sollte keine Mehrprojekt-Studie behaupten, bevor sie durchgeführt wurde. Messen Sie vier Wochen lang aktive Autorenzeit, Review-Wartezeit, SME-/Redaktionszeit, Fehler nach Veröffentlichung, Zeit bis Production und False Positives. Automatisieren Sie anschließend etwa Links, Metadaten und Build und wiederholen Sie die Messung.
So entsteht eine belastbare Fallstudie mit Kontext statt einer dekorativen Zahl.
Menschen und Maschinen prüfen unterschiedliche Dinge
| Maschine | Mensch |
|---|---|
| Link existiert | Link hilft dem Nutzer |
| Heading existiert | Struktur folgt der Aufgabe |
| Begriff ist erlaubt | Begriff ist verständlich |
| Beispiel passt zum Schema | Beispiel erklärt einen echten Use Case |
| Seite baut | Seite ermöglicht Erfolg |
LLM-Checks können Widersprüche markieren, aber Fakten müssen gegen Produkt, Spezifikation, Test oder verantwortlichen Experten geprüft werden.
Wo Fanatismus beginnt
Fanatismus beginnt, wenn Prozessreinheit wichtiger als Beteiligte wird. Kann ein SME einen Parameternamen in zwei Minuten im Browser korrigieren, braucht er nicht Node.js, lokalen Clone und Rebase. Bieten Sie Browser Editing, Issue-Templates, Assisted Authoring oder eine Person als Übergang in den Git-Prozess.
Docs-as-Code schrittweise einführen
- Woche 1: Quellen nach Git, Historie verständlich machen.
- Woche 2: Preview und automatischen Build hinzufügen.
- Woche 3: drei bis fünf nützliche Checks aktivieren.
- Woche 4: technisches und redaktionelles Review bei Bedarf trennen.
- Nach einem Monat: Lead Time, Routine, Fehler und Warning-Rauschen messen.
Docs-as-Code ist erfolgreich, wenn Ändern, Prüfen und Veröffentlichen leichter werden.
