Engineering Documentation: So schreibst

Dienstagmorgen, ein Kollege ist krank. Genau er kennt den Deployment-Workflow für den neuen Microservice. Das Wissen steckt in seinem Kopf, in Slack-Threads und in drei Notizen, die niemand sofort findet.

So sieht Engineering Documentation im Alltag vieler Teams aus. Die technische Lösung funktioniert, aber ihre Entstehung, ihre Abhängigkeiten und ihre Betriebslogik bleiben schwer zugänglich. Der versteckte Aufwand entsteht dann nicht beim Schreiben, sondern beim Suchen, Nachfragen und Rekonstruieren.

Eine Studie zu agilen Softwareprojekten in Deutschland mit 104 Teilnehmenden zeigt, wie gross dieser Aufwand werden kann: Die Befragten schätzten ihren Dokumentationsaufwand im Mittel auf 16 % der Arbeitszeit, während der gemessene Informationssuchanteil bei 25 % lag. In der Tätigkeitsanalyse wurden dagegen 4 % für Dokumentation und 7 % für Informationssuche beobachtet. Die Studienergebnisse von Sprintdoc liefern damit einen wichtigen Hinweis: Dokumentation und Informationssuche müssen näher an den Entwicklungsprozess rücken.

Inhaltsverzeichnis

• Warum Engineering Documentation im Alltag oft scheitert
  • Der Aufwand versteckt sich zwischen den Aufgaben
• Eine schlanke Struktur für technische Dokumentation aufbauen
  • Vier Dokumenttypen, ein gemeinsames Gerüst
  • Metadaten verhindern stille Veralterung
• Tools und Formate für Engineering Documentation auswählen
  • Entscheide nach dem tatsächlichen Risiko
• Workflows für Versionierung und Zusammenarbeit etablieren
  • Verantwortung verteilt sich besser
• Mit Spracheingabe schneller und flüssiger dokumentieren
  • Ein Diktat, das brauchbaren Rohtext erzeugt
• Praxis-Checkliste für bessere Engineering Documentation

Warum Engineering Documentation im Alltag oft scheitert

Der kranke Kollege ist nicht das eigentliche Problem. Das Problem ist, dass der Rest des Teams keinen verlässlichen Weg kennt, um sein Wissen zu ersetzen. Eine Person sucht im Repository, eine andere fragt in Slack, eine dritte öffnet alte Tickets. Nach kurzer Zeit diskutieren alle über Vermutungen statt über überprüfbare Informationen.

Agile Arbeit verstärkt dieses Muster. Das Team priorisiert Features, behebt Fehler und liefert Releases. Dokumentation bleibt dabei oft eine Zusatzaufgabe, die erst nach dem eigentlichen Ergebnis beginnen soll. Genau dann fehlt der Kontext, oder die nächste Änderung steht bereits an.

Der Aufwand versteckt sich zwischen den Aufgaben

Engineering Documentation scheitert selten an fehlender Disziplin. Sie scheitert an Kontextwechseln. Du musst dich aus dem Code herausarbeiten, die richtigen Informationen auswählen, ein Format finden und später prüfen, ob die Beschreibung noch stimmt.

Diese Reibung taucht an vielen Stellen auf:

• Onboarding: Neue Teammitglieder fragen wiederholt nach Architektur, lokalen Abläufen und typischen Fehlerbildern.

• Incident Response: Während eines Vorfalls fehlen Runbooks, aktuelle Abhängigkeiten oder klare Hinweise für Rollback und Eskalation.

• Architekturentscheidungen: Das Team kennt die aktuelle Lösung, aber nicht mehr den Grund, warum eine Alternative verworfen wurde.

• Wartung: Kleine Änderungen machen alte Anleitungen unzuverlässig, ohne dass jemand den veralteten Inhalt bewusst bemerkt.

Praktische Regel: Wenn eine Information beim nächsten ähnlichen Vorgang erneut gesucht wird, gehört sie in eine auffindbare Dokumentation.

Die deutsche Engineering-Basis macht diese Aufgabe besonders relevant. Eine öffentlich verfügbare Übersicht beziffert die Zahl der Beschäftigten in ingenieurbezogenen Berufen auf mehr als 1,94 Millionen. Davon entfallen rund 1 Million auf Ingenieurinnen und Ingenieure, 926.000 auf Technologen und Techniker sowie 18.000 auf Geologinnen und Geologen. Der Anteil lag 2010 bei etwa 4,7 % der Gesamtbeschäftigung. Die Übersicht zur Engineering Labour Force in Germany zeigt damit die Grösse und Spezialisierung der Arbeitswelt, in der technische Dokumentation funktionieren muss.

Die Konsequenz ist klar: Dokumentation darf kein nachgelagerter Bericht sein. Sie sollte dort entstehen, wo Entscheidungen fallen, Funktionen fertig werden und Betriebswissen noch präsent ist. Ein kurzer Entwurf direkt nach einer Änderung ist meist wertvoller als ein perfektes Dokument, das Wochen später mühsam rekonstruiert wird.

Wenn du Spracheingabe als Teil dieses Workflows einsetzen willst, findest du einen praktischen Einstieg zur Schreibgeschwindigkeit auf der fluesta-Seite zur Geschwindigkeit.

Eine schlanke Struktur für technische Dokumentation aufbauen

Eine gute Struktur beginnt nicht mit maximaler Vollständigkeit. Sie beginnt mit der Frage: Welche Information soll eine konkrete Person in einer konkreten Situation finden?

Als gedanklichen Rahmen nutze ich gern Diátaxis. Das Modell trennt Tutorials zum Lernen, How-to-Guides zum Erledigen einer Aufgabe, Referenzdokumente zum Nachschlagen und Erklärungen für Zusammenhänge. Die Kategorien helfen, unterschiedliche Erwartungen nicht auf einer einzigen Seite zu vermischen.

Vier Dokumenttypen, ein gemeinsames Gerüst

Lege zuerst ein zentrales Doc-Repository oder einen klaren Dokumentationsbereich an. Die genaue Plattform ist weniger entscheidend als die eindeutige Adresse und die Regel, dass niemand die verbindliche Version auf dem lokalen Desktop speichert.

Eine schlanke Struktur kann so aussehen:

• Start: Überblick, Zielgruppe und erster erfolgreicher Einstieg.

• How-to: Konkrete Abläufe, etwa Deployment, Rollback oder das Anlegen eines neuen Endpoints.

• Referenz: API-Spezifikation, Konfigurationswerte, Fehlermeldungen und Schnittstellen.

• Erklärung: Architektur, Abhängigkeiten, wichtige Trade-offs und Architecture Decision Records.

Trenne dabei lebendige Dokumentation von stabiler Referenz. Ein ADR beschreibt eine Entscheidung und ihren Kontext. Eine API-Referenz sollte dagegen möglichst nah an der tatsächlichen Schnittstelle bleiben und nicht mit langen Begründungen überladen werden.

Metadaten verhindern stille Veralterung

Jedes Dokument braucht wenige, aber verbindliche Angaben:

• Owner: Wer beantwortet Fragen und koordiniert Updates?

• Status: Entwurf, aktiv, veraltet oder archiviert.

• Last Review: Wann wurde der Inhalt zuletzt geprüft?

• Scope: Für welches System, Team oder Release gilt die Information?

Das ist kein Verwaltungsaufwand um seiner selbst willen. Metadaten machen sichtbar, welche Inhalte Pflege brauchen. Ohne Owner fühlt sich niemand zuständig. Ohne Status behandelt das Team einen Entwurf schnell wie eine verbindliche Referenz.

Templates sollten kurz genug sein, dass Entwickler sie in unter fünf Minuten ausfüllen können. Eine strukturierte Dokumentationsbasis von fluesta kann dabei als Ausgangspunkt dienen, wichtiger bleibt aber die Anpassung an eure Systeme.

Ein gutes Template fragt nicht nach allem. Es fragt nach dem, was der Leser wirklich braucht: Zweck, Einstieg, Abhängigkeiten, typische Fehler, Änderungshistorie und nächste Ansprechperson. Für ein Runbook ist das eine andere Auswahl als für eine Architekturentscheidung.

Merksatz: Ein Dokument ist nicht vollständig, wenn es lang ist. Es ist vollständig, wenn der Leser seine Aufgabe ohne unnötige Rückfragen erledigen kann.

Tools und Formate für Engineering Documentation auswählen

Die Tool-Frage wird schnell ideologisch. Confluence, Notion und Docs-as-Code können alle funktionieren. Entscheidend ist, wie euer Team arbeitet und welche Eigenschaften im Alltag zählen: Suche, Versionierung, Berechtigungen, Review und Veröffentlichung.

Ein Wiki eignet sich, wenn viele Menschen Inhalte direkt bearbeiten sollen und der Einstieg ohne lokale Entwicklungsumgebung wichtig ist. Confluence bringt eine etablierte Wissensbasis für Teams mit, während Notion eine flexible Arbeitsumgebung für gemischte Inhalte bietet. Beide brauchen allerdings klare Regeln, damit Seiten nicht ungeordnet wachsen und veraltete Versionen nebeneinander stehen.

Docs-as-Code passt gut, wenn technische Dokumentation eng am Repository und am Release-Prozess liegt. Markdown lässt sich in Pull Requests reviewen. MkDocs, Docusaurus und Sphinx können daraus strukturierte Dokumentationsseiten bauen. OpenAPI eignet sich für maschinenlesbare API-Referenz, Mermaid für nachvollziehbare Diagramme und ADR-Templates für Architekturentscheidungen.

Entscheide nach dem tatsächlichen Risiko

Frage nicht zuerst, welches Tool modern wirkt. Frage, wo ein Fehler teuer wird. Eine API-Referenz sollte mit dem Code oder der Spezifikation synchron bleiben. Ein Onboarding-Tutorial braucht klare Sprache und einen getesteten Einstieg. Ein Incident-Runbook muss schnell auffindbar und realitätsnah sein.

Auch die Suche verdient einen Test mit echten Fragen. Suche nach einem Service-Namen, einem Fehlerbild und einer Architekturentscheidung. Wenn du dabei nur über Seitenhierarchien navigieren kannst, wird das System unter Zeitdruck nicht zuverlässig funktionieren.

Diagramme sollten als bearbeitbare Quellen vorliegen. Mermaid ist praktisch, weil Änderungen im Review sichtbar bleiben. Bilder aus Präsentationen sehen oft sauber aus, werden aber schnell zu statischen Inseln.

Entscheidungshilfe: Wähle das Format, das deine häufigste Änderung am einfachsten durch den Review bringt.

Für die systemweite Spracheingabe in technischen und organisatorischen Textfeldern kann die fluesta-Dokumentation den Einrichtungs- und Nutzungsworkflow abbilden. fluesta funktioniert systemweit in jedem Programm, verarbeitet Sprache als Text und positioniert die Ausgabe direkt im aktiven Eingabefeld. Für sensible Arbeitsumgebungen nennt fluesta Zero Data Retention, EU-Hosting und den Verzicht auf den US Cloud Act als zentrale Eigenschaften.

Workflows für Versionierung und Zusammenarbeit etablieren

Dokumentation bleibt aktuell, wenn sie denselben Weg wie eine relevante Codeänderung nimmt. Speichere sie deshalb nicht als persönliche Datei, sondern in einem versionierten Repository oder in einem System, das Änderungen nachvollziehbar protokolliert.

Für viele Teams reicht ein schlanker Ablauf:

1. Änderung identifizieren: Verknüpfe die Dokumentation mit Feature, Bug, Incident oder ADR.

2. Branch anlegen: Bündele zusammengehörige Änderungen in einem Branch.

3. Dokument aktualisieren: Ändere Text, Diagramme und Metadaten gemeinsam.

4. Pull Request öffnen: Beschreibe, was sich für Leser verändert.

5. Review durchführen: Eine zweite Person prüft Inhalt, Verständlichkeit und Aktualität.

6. Veröffentlichen oder mergen: Erst danach wird die Änderung zur verbindlichen Version.

Die wichtigste Regel lautet: Reviewe Dokumentation mit demselben Ernst wie produktionsnahen Code, aber mit einem passenden Umfang. Nicht jede Kommakorrektur braucht ein langes Meeting. Ein neues Deployment-Verfahren oder eine geänderte Datenabhängigkeit braucht dagegen eine fachkundige Prüfung.

Verantwortung verteilt sich besser

Ein einzelner Technical Writer oder Tech Lead kann Standards setzen. Er sollte aber nicht der einzige Mensch sein, der Inhalte aktualisiert. Eine Doc-Owning-Rotation verteilt Wissen und verhindert, dass Krankheit, Urlaub oder Teamwechsel den Zugriff blockieren.

Definiere vor dem Schreiben ein kurzes Prüfraster:

• Sind Zielgruppe und Zweck erkennbar?

• Stimmen Codebeispiele und Diagramme?

• Sind Abhängigkeiten und betroffene Dokumente verlinkt?

• Ist der Owner noch die richtige Person?

• Gibt es einen klaren Umgang mit veralteten Inhalten?

CI kann dabei einfache Fehler melden. Link-Checks, Pflichtfelder, Formatregeln und Vorschau-Builds reduzieren manuelle Routine. Inhaltliche Richtigkeit bleibt trotzdem eine menschliche Aufgabe.

Die Normenlandschaft bestätigt, dass technische Produktdokumentation nicht nur interne Büroarbeit ist. DINs Übersicht zum Dokumentationswesen führt für technische Produktdokumentation und Dokumentenmanagement unter anderem die DIN EN ISO 128-1 sowie DIN 199-1, Ausgabe 2024-06, und verweist auf weitere verwandte Normen. Für Unternehmen bedeutet das: Dokumentstrukturen, Zeichnungen und Spezifikationen gehören zu Entwicklung, Fertigung, Qualitätssicherung und Compliance.

Mit Spracheingabe schneller und flüssiger dokumentieren

Beim Tippen formulierst du Inhalt und steuerst gleichzeitig die Tastatur. Bei komplexen Architektur- oder Incident-Texten zerfällt dadurch oft der Gedankengang. Spracheingabe verschiebt den Schwerpunkt: Du formulierst zuerst, strukturierst danach.

Eine klinische Studie verglich diktierte und getippte Notizen. Diktierte Notizen waren im Schnitt 320,6 Wörter lang, getippte Notizen 180,8 Wörter. Die Dokumentationszeit war ähnlich, diktierte Notizen wurden sogar leicht schneller fertig. Die Studie zu diktierten und getippten Notizen liefert damit einen konkreten Hinweis auf den Produktivitätshebel von Spracheingabe.

Das heisst nicht, dass jedes Diktat automatisch gute Dokumentation ergibt. Sprache produziert Rohmaterial. Gute Engineering Documentation braucht danach Struktur, Begriffe, Beispiele und eine Prüfung durch jemanden, der das System kennt.

Ein Diktat, das brauchbaren Rohtext erzeugt

Sprich in kurzen Sinneinheiten. Nenne Überschriften ausdrücklich und markiere Übergänge, statt zehn Minuten ohne Pause zu sprechen.

Ein praktikabler Ablauf sieht so aus:

• Vorlage öffnen: Starte mit festen Überschriften für Zweck, Kontext, Ablauf, Fehlerbilder und Owner.

• Inhalt diktieren: Sprich einen Abschnitt nach dem anderen und bleib bei einer Aussage pro Satz.

• Fachbegriffe isolieren: Pausiere kurz vor Produktnamen, Services, Bibliotheken und Abkürzungen.

• Struktur korrigieren: Ergänze Listen, Codeblöcke, Links und Diagramme erst nach dem vollständigen Diktat.

• Fakten prüfen: Vergleiche Namen, Pfade, Parameter und Abhängigkeiten mit der tatsächlichen Implementierung.

Otter.ai, Google Docs Voice Typing und Microsoft Dictate können für Spracheingabe passende Optionen sein. Für vertrauliche Engineering-Inhalte zählen neben Erkennungsqualität auch Speicherort, Löschung und Rechtsgrundlage.

In der EU gelten Sprachaufnahmen als personenbezogene Daten, sobald eine Person direkt oder indirekt identifizierbar ist. Daraus folgen Anforderungen an Rechtsgrundlage, Transparenz, Speicherbegrenzung und Löschung. Die Übersicht zu AI, Voice Data und DSGVO beschreibt diese Pflichten für den Umgang mit Sprachdaten.

Artikel 5 Absatz 1 Buchstabe e der DSGVO verlangt eine Begrenzung der Speicherdauer. Für Voice- und Transkriptionsdaten sollten Retentionsfristen deshalb ausdrücklich definiert und technisch durchgesetzt werden, wie die Erläuterung zur AI-Voice-Transkription hervorhebt.

Praxis-Checkliste für bessere Engineering Documentation

Morgen brauchst du kein neues Framework. Du brauchst einen Ablauf, der beim nächsten Feature, Incident oder Architekturentscheid tatsächlich ausgeführt wird.

Prüfe jedes neue oder grundlegend geänderte Dokument mit diesen sechs Fragen:

• Ziel geklärt: Weiss der Leser, welche Aufgabe das Dokument unterstützt?

• Zielgruppe definiert: Ist klar, ob der Inhalt für Onboarding, Betrieb, Entwicklung oder Referenz gedacht ist?

• Zuständigkeit festgelegt: Gibt es einen Owner, der fachliche Updates koordiniert?

• Ort eindeutig: Liegt die verbindliche Version an einem zentral bekannten Speicherort?

• Versionierung vorhanden: Lassen sich Änderungen, Reviews und frühere Stände nachvollziehen?

• Review-Zyklus etabliert: Gibt es einen festen Anlass oder Rhythmus für die Prüfung?

Die Checkliste wirkt bewusst einfach. Genau das ist ihre Stärke. Ein Team kann sie in den Pull Request übernehmen, als Template speichern oder bei der wöchentlichen Pflege verwenden.

Achte zusätzlich auf die Form der Information. Ein Tutorial soll jemanden sicher zum Ergebnis führen. Ein Runbook soll im Stress funktionieren. Eine Referenz soll vollständig und präzise sein. Eine Erklärung soll Entscheidungen verständlich machen, ohne operative Schritte zu verstecken.

Gute Dokumentation beantwortet nicht jede mögliche Frage. Sie verhindert die wiederkehrenden Fragen, die dein Team Zeit kosten.

Prüfe verwaiste Dokumente regelmässig. Markiere Seiten, deren Owner nicht mehr zuständig ist, aktualisiere geänderte Abläufe und archiviere Inhalte, die keine gültige Anwendung mehr haben. So bleibt das Vertrauen in die Suche erhalten.

Wenn du Spracheingabe in diesen Prozess integrierst, entsteht der Text dort, wo dein Wissen noch frisch ist. fluesta bietet dafür eine systemweite Diktierlösung für Mac und Windows, mit 150+ Wörtern pro Minute, 3x schneller als Tippen, EU-gehosteter Verarbeitung und Zero Data Retention. Der Pro-Plan kostet 14 Euro pro Monat, aktuell gilt in der Betaphase ein 50-%-Rabatt.

---

Wenn du Engineering Documentation ohne zusätzlichen Kontextwechsel in deinen bestehenden Tools erstellen willst, probiere fluesta als Spracheingabe für Mac und Windows aus. Sprich deine Architekturentscheidung, dein Runbook oder deine Fehleranalyse direkt an der Cursor-Position ein und besuche dafür fluesta.