
Technical Documentation, auf Deutsch technische Dokumentation, erklärt ein technisches Produkt, System oder Verfahren so, dass eine bestimmte Zielgruppe eine konkrete Aufgabe sicher und nachvollziehbar erledigen kann. Gute Dokumentation sammelt deshalb nicht einfach alles, was ein Team weiß. Sie trennt Anleitung, Referenz, Erklärung und Fehlerbehebung, nennt Voraussetzungen und Grenzen und macht sichtbar, wer Inhalt und Aktualität verantwortet. Dieser Leitfaden richtet sich an Technical Writer, Produkt- und Entwicklungsteams, die Software- oder interne Prozessdokumentation planen. Du lernst, eine kopierbare Vorlage zu füllen und Review sowie Pflege zu organisieren.
In diesem Leitfaden: Dokumenttypen wählen · Zielgruppe klären · Vorlage kopieren · acht Schritte umsetzen · Beispiel prüfen · Qualität messen · Pflege organisieren · Formate abgrenzen · AFFiNE einsetzen · FAQ lesen
Die Frage „Welche Kapitel gehören in technische Dokumentation?“ ist zu früh. Zuerst muss klar sein, was eine Person nach dem Lesen können oder verstehen soll. Das Diátaxis-Framework unterscheidet vier Zwecke: Tutorial, How-to, Referenz und Erklärung. Für ein Softwareteam lässt sich das um Architektur, Betrieb und interne Prozesse ergänzen.
| Dokumenttyp | Leserfrage | Typischer Inhalt | Häufiger Fehler |
|---|---|---|---|
| Tutorial oder Einstieg | Wie lerne ich den Ablauf? | geführtes Beispiel, kleine sichere Schritte | zu viele Sonderfälle im Lernpfad |
| Anleitung oder How-to | Wie löse ich Aufgabe X? | Voraussetzungen, nummerierte Schritte, Ergebnis | Hintergrund statt Handlung |
| API- oder technische Referenz | Welche Parameter und Grenzen gelten? | Schnittstellen, Datentypen, Rückgaben, Fehler | ungetestete Beispiele |
| Architektur und Erklärung | Warum ist das System so aufgebaut? | Komponenten, Entscheidungen, Abhängigkeiten | Diagramm ohne Text oder Stand |
| Betrieb und Troubleshooting | Wie erkenne und behebe ich ein Problem? | Symptome, Diagnose, Maßnahmen, Eskalation | nur der Idealfall |
| interne Prozessdokumentation | Wer macht was und wann? | Rollen, Übergaben, Freigabe, Nachweis | kein Owner, kein Review-Datum |
Die Trennung hilft auch beim Verlinken: Eine kurze Anleitung kann auf Referenz und Architektur verweisen, ohne deren Inhalte zu kopieren. Für größere Sammlungen brauchst du zusätzlich eine klare Informationsarchitektur. Wer noch eine Wissensdatenbank-Software auswählen muss, findet im Vergleich Hilfe bei der System- und Governance-Frage; hier geht es um die Qualität eines einzelnen Dokumentationsprozesses.
„Entwickler“ ist noch keine ausreichende Zielgruppe. Ein neuer Frontend-Entwickler, eine externe Integrationspartnerin und der Bereitschaftsdienst bringen anderes Vorwissen mit. Schreibe vor der Gliederung vier Sätze:
Ein brauchbarer Job to be done lautet zum Beispiel: „Ein neues Mitglied des Plattformteams rotiert einen API-Schlüssel in der Staging-Umgebung, prüft den erfolgreichen Wechsel und weiß, wann es eskalieren muss.“ Damit werden Struktur und Prüfkriterien konkret. „API-Schlüssel dokumentieren“ bleibt dagegen offen.
Wenn die Aufgabe zuerst zerlegt werden muss, hilft ein Projektstrukturplan. Er ersetzt die Dokumentation nicht, macht aber Arbeitspakete, Abhängigkeiten und Zuständigkeiten sichtbar.
Kopiere diese Dokumentationsvorlage in dein Wiki, Repository oder Dokument. Entferne Felder nur bewusst; ein leeres Feld ist häufig ein Signal, dass Scope oder Verantwortung noch unklar sind.
| Feld | Eintrag |
|---|---|
| Titel und Zweck | Was erklärt das Dokument und welches Ergebnis ermöglicht es? |
| Zielgruppe | Rolle, Vorwissen, Nutzungssituation |
| Scope / Nicht im Scope | System, Version, Umgebung sowie bewusste Ausschlüsse |
| Owner | verantwortliche Rolle oder Team; keine Sammeladresse ohne Zuständigkeit |
| Version / Gültigkeitsstand | Produkt-, API-, Prozess- oder Dokumentversion |
| Status | Entwurf, im technischen Review, freigegeben, veraltet oder archiviert |
| Voraussetzungen | Zugriff, Werkzeuge, Daten, Begriffe, Sicherheitsbedingungen |
| Ablauf | nummerierte, einzeln prüfbare Schritte |
| Erwartetes Ergebnis | sichtbarer Zustand nach jedem kritischen Schritt |
| Beispiel | realistischer, als Beispiel gekennzeichneter Fall |
| Fehlerfälle | Symptom, wahrscheinliche Ursache, sichere Maßnahme, Eskalation |
| Quellen und Entscheidungen | Primärquellen, ADRs, Tickets oder Spezifikationen |
| Fachlicher Review | Name oder Rolle, Datum und Ergebnis |
| Nächster Review / Trigger | Datum und Ereignisse, die eine frühere Prüfung auslösen |
Die Vorlage ist eine redaktionelle Best Practice, keine universelle Norm und keine Compliance-Vorlage. Für Maschinen, Medizinprodukte, sicherheitskritische Systeme oder andere regulierte Produkte müssen die jeweils geltenden Rechts- und Normanforderungen von qualifizierten Verantwortlichen bestimmt werden. Schon die Scope-Beschreibung der DIN SPEC 3105-1 zeigt, dass Standards einen abgegrenzten Anwendungsbereich haben und andere Regelwerke nicht pauschal ersetzen.
Formuliere Aufgabe, Zielgruppe, Systemstand und Ausschlüsse. Definiere ein prüfbares Ergebnis: Ein Testkonto ist eingerichtet, ein Request liefert die erwartete Antwort oder ein Dienst ist nach einem Fehler wieder stabil.
Sammle Primärquellen: Code, Schnittstellenspezifikation, Produktentscheidung, Prozessbeschreibung und zuständige Fachperson. Trenne belegte Fakten von Annahmen und offenen Fragen.
Entscheide, ob Leser lernen, eine Aufgabe erledigen, Fakten nachschlagen oder eine Entscheidung verstehen sollen. Erstelle lieber zwei verlinkte Dokumente als eine Seite, die Tutorial und vollständige Referenz vermischt.
Ordne Einstieg, Voraussetzungen, Ablauf, Ergebnis, Fehlerfälle und weiterführende Quellen. Verwende Überschriften, die auch in einer Suche verständlich sind. „Fehler 401 nach Tokenwechsel beheben“ ist auffindbarer als „Weitere Hinweise“.
Schreibe nicht nur aus Erinnerung. Führe die Schritte in der angegebenen Umgebung aus, kopiere Werte nicht blind zwischen Versionen und dokumentiere Abweichungen. Screenshots brauchen sichtbaren Stand und Alt-Text; sensible Daten gehören nicht hinein.
Eine Fachperson testet Inhalt, Befehle, Voraussetzungen und Fehlerfälle. Eine zweite Perspektive prüft Sprache, Terminologie, Struktur und Zugänglichkeit. Der Google Developer Documentation Style Guide behandelt Klarheit und Konsistenz ausdrücklich als anpassbare Leitlinien, nicht als Ersatz für projektspezifische Regeln.
Setze Status, Owner, Version und Review-Datum. Verlinke die Seite aus dem passenden Einstieg, Runbook oder Projektbereich. Eine perfekte Seite ohne navigierbaren Zugang ist praktisch unsichtbar.
Definiere Ereignisse statt nur einen jährlichen Kalendereintrag: API-Änderung, neue Fehlermeldung, Rollenwechsel, geänderte Berechtigung, Supporthäufung oder Sicherheitsupdate. Ein fester Review bleibt die Rückfallebene.
Das folgende Beispiel ist fiktiv und redaktionell. Namen, Versionen und Zeiträume sind keine AFFiNE-Produktangaben.
| Feld | Beispielwert |
|---|---|
| Zweck | Einen API-Schlüssel in Staging ersetzen, Erfolg prüfen und alten Schlüssel widerrufen |
| Zielgruppe | Plattformteam; Grundkenntnisse der Deployment-Konsole |
| Owner | Platform Operations |
| Version / Status | Dokument 1.3; freigegeben |
| Gültig für | Auth-Service 2.4; Staging; nicht Produktion |
| Voraussetzungen | Vier-Augen-Freigabe, Staging-Zugriff, Wartungsfenster von 30 Minuten |
| Schritte | neuen Schlüssel erzeugen; Secret aktualisieren; Dienst neu laden; Testrequest prüfen; Logs 15 Minuten beobachten; alten Schlüssel widerrufen |
| Erfolg | Testrequest liefert erwarteten Status; keine Auth-Fehler im Beobachtungsfenster |
| Fehlerfall | bei steigender 401-Rate Rollback auf vorheriges Secret und Eskalation an den Bereitschaftsdienst |
| Review | technisch geprüft am 12.08.2026; erneute Prüfung nach Auth-Änderung oder spätestens nach 90 Tagen |
Das Beispiel zeigt den Unterschied zwischen Schritt und Nachweis. „Secret aktualisieren“ ist eine Handlung; „Testrequest erfolgreich und 15 Minuten ohne neue Auth-Fehler“ ist die überprüfbare Evidenz. In einer echten Anleitung müssen Befehle, Schwellenwerte und Rollback vom zuständigen Team bestätigt werden.
Prüfe eine Seite nicht nach Textmenge, sondern nach Nutzung:
Notizen können Rohmaterial liefern, sind aber noch keine freigegebene Dokumentation. Wenn du Erfassung und Ablage zuerst klären musst, vergleicht der Leitfaden deutsche Notizen-Apps nach praktischen Nutzungsszenarien.
Ein robuster Dokumentationsprozess hat fünf Zustände: planen → schreiben → technisch prüfen → freigeben → pflegen. „Freigegeben“ heißt nicht „für immer fertig“. Lege für jeden Übergang eine verantwortliche Rolle fest:
Nutze zwei Pflegewege. Der ereignisbasierte Review reagiert sofort auf Produkt-, API-, Prozess- oder Sicherheitsänderungen. Der periodische Review findet Seiten, die ohne sichtbares Ereignis veraltet sind. Für kritische Runbooks kann ein kürzerer Zyklus angemessen sein; für stabile Erklärtexte ein längerer. Die Frist ist eine Teamentscheidung, keine universelle Regel.
| Format | Hauptzweck | Typischer Inhalt | Abgrenzung |
|---|---|---|---|
| technische Dokumentation | System oder technische Aufgabe verständlich machen | Anleitung, Referenz, Architektur, Betrieb | kann mehrere Formate enthalten |
| Wissensdatenbank | viele auffindbare Antworten organisieren | verlinkte Artikel, Suche, Kategorien | ist der Container, nicht automatisch der Qualitätsprozess |
| SOP | einen wiederholbaren Prozess standardisieren | Rollen, Reihenfolge, Kontrollen, Nachweis | enger und prozessorientierter |
| PRD | Produktbedarf und gewünschtes Ergebnis beschreiben | Problem, Nutzer, Anforderungen, Erfolg | erklärt meist, was gebaut werden soll, nicht den späteren Betrieb |
Die Grenzen dürfen sich überlappen. Ein Runbook ist technische Dokumentation und kann zugleich als SOP dienen. Wichtig ist, dass Leser Zweck, Status und Geltungsbereich erkennen, statt vier Bezeichnungen für dieselbe ungepflegte Seite zu verwenden.
Wie mehrere Anleitungen und Entscheidungsnotizen gemeinsam auffindbar bleiben, zeigt der Leitfaden zum Aufbau einer internen Wissensdatenbank.
AFFiNE verbindet laut der deutschen Produktseite Dokumente, Whiteboards, Datenbanken und KI in einem Local-First-Workspace. Für technische Dokumentation kann daraus ein nachvollziehbarer Arbeitsraum entstehen:
AFFiNE ersetzt dabei keine Docs-as-Code-Pipeline, generiert nicht automatisch eine belastbare API-Referenz und prüft keine Compliance. Solche Anforderungen brauchen spezialisierte Werkzeuge und Verantwortliche. Der Vorteil liegt im gemeinsamen Kontext von Text, visueller Erklärung und verknüpftem Wissen. Liegt deine Dokumentation heute in Confluence, hilft der Vergleich Confluence Alternative für Dokumentation, Importwege, Makros und Berechtigungen vor einem Wechsel abzuwägen.
Sie sollte Zweck, Zielgruppe, Geltungsbereich, Voraussetzungen, nachvollziehbare Schritte oder Referenzdaten, Beispiele, Fehlerfälle, Quellen, Owner, Status, Version und Review-Trigger enthalten. Welche Felder wirklich nötig sind, hängt vom Dokumenttyp und vom Risiko der beschriebenen Aufgabe ab.
Häufig sind Tutorials, konkrete How-to-Anleitungen, technische Referenzen und erklärende Architekturtexte. Dazu kommen Betriebsdokumentation, Troubleshooting, Runbooks und interne Prozessdokumentation. Trenne die Formate nach Leseraufgabe, statt alle Inhalte in einer langen Seite zu mischen.
Definiere sowohl Ereignisse als auch einen periodischen Review. Produkt-, API-, Berechtigungs- oder Sicherheitsänderungen lösen sofort eine Prüfung aus. Ein zusätzlicher Termin fängt stille Alterung ab. Das passende Intervall hängt von Änderungsrate, Kritikalität und Nutzung ab.
Mindestens eine fachkundige Person sollte technische Richtigkeit und ausführbare Schritte prüfen. Bei sicherheitskritischen, rechtlich relevanten oder regulierten Inhalten müssen zusätzlich die dafür qualifizierten Verantwortlichen freigeben. Autor, Fachreview, Freigabe und dauerhafter Owner können unterschiedliche Rollen sein.
AFFiNE eignet sich für Teams, die Text, Diagramme, verknüpfte Notizen und Statusübersichten in einem Arbeitsbereich halten wollen. Für automatische API-Referenzen, formale Compliance-Freigaben oder eine vollständige Docs-as-Code-Pipeline brauchst du ergänzende Spezialwerkzeuge.
Gute Technical Documentation beginnt mit Zielgruppe und Aufgabe, wählt den passenden Dokumenttyp und macht jeden kritischen Schritt prüfbar. Die Vorlage gibt dir einen Startpunkt; Owner, Status, Review und Update-Trigger halten sie nutzbar. Nimm für den ersten Durchlauf ein konkretes Verfahren, teste es mit einer Person aus der Zielgruppe und korrigiere die Stellen, an denen sie suchen, raten oder nachfragen muss.
Redaktion und Transparenz: Dieser Beitrag wurde vom AFFiNE-Team erstellt. Die Ahrefs- und GSC-Werte dienten nur der Themenwahl und stehen nicht im redaktionellen Argument. Das Softwarebeispiel ist fiktiv. Es bestehen keine Affiliate-Links. Produktangaben wurden am 16.08.2026 gegen offizielle AFFiNE-Seiten geprüft; Korrekturhinweise können über die redaktionellen Richtlinien eingereicht werden.
Quellen, abgerufen am 16.08.2026: Diátaxis · Google Developer Documentation Style Guide · W3C Web Accessibility Initiative · DIN Media: DIN SPEC 3105-1 · AFFiNE auf Deutsch · AFFiNE Download