Alle Beiträge
AFFiNE
Toeverything·Veröffentlicht 16. Aug. 2026
Informationsarchitektur mit Zielgruppe, Dokumenttypen, Review und Pflege

Technical Documentation: Leitfaden, Vorlage und Beispiel

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.

Das Wichtigste in Kürze

  • Beginne mit Zielgruppe und Aufgabe, nicht mit einem Inhaltsverzeichnis.
  • Trenne Lernpfad, konkrete Anleitung, technische Referenz und Hintergrund. Ein Dokument muss nicht alle vier Zwecke gleichzeitig erfüllen.
  • Jede wichtige Seite braucht Owner, Version oder Gültigkeitsstand, Status, fachlichen Review und einen Auslöser für die nächste Prüfung.
  • Ein Beispiel ist nur dann hilfreich, wenn Leser erkennen, welche Werte echt, variabel oder rein redaktionell sind.
  • Interne Softwaredokumentation ist nicht automatisch die technische Produktdokumentation, die in einem regulierten Kontext verlangt wird.

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

Dokumenttypen nach Aufgabe und Zielgruppe

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.

DokumenttypLeserfrageTypischer InhaltHäufiger Fehler
Tutorial oder EinstiegWie lerne ich den Ablauf?geführtes Beispiel, kleine sichere Schrittezu viele Sonderfälle im Lernpfad
Anleitung oder How-toWie löse ich Aufgabe X?Voraussetzungen, nummerierte Schritte, ErgebnisHintergrund statt Handlung
API- oder technische ReferenzWelche Parameter und Grenzen gelten?Schnittstellen, Datentypen, Rückgaben, Fehlerungetestete Beispiele
Architektur und ErklärungWarum ist das System so aufgebaut?Komponenten, Entscheidungen, AbhängigkeitenDiagramm ohne Text oder Stand
Betrieb und TroubleshootingWie erkenne und behebe ich ein Problem?Symptome, Diagnose, Maßnahmen, Eskalationnur der Idealfall
interne ProzessdokumentationWer macht was und wann?Rollen, Übergaben, Freigabe, Nachweiskein Owner, kein Review-Datum
Matrix der Dokumenttypen, Zielgruppen und jeweiligen Leseraufgaben
Die Leseraufgabe entscheidet, ob Tutorial, Anleitung, Referenz, Erklärung, Betriebs- oder Prozessdokumentation passt.

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.

Zielgruppe und „Job to be done“ vor der Gliederung

„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:

  1. Wer liest? Rolle, Erfahrungsniveau und Arbeitskontext.
  2. Was soll danach möglich sein? Ein beobachtbares Ergebnis, etwa „einen Testzugang einrichten“.
  3. Was wird vorausgesetzt? Berechtigungen, Werkzeuge, Begriffe und Systemstand.
  4. Was gehört ausdrücklich nicht dazu? Varianten, die ein anderes Dokument oder eine Fachfreigabe benötigen.

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.

Vorlage für technische Dokumentation

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.

FeldEintrag
Titel und ZweckWas erklärt das Dokument und welches Ergebnis ermöglicht es?
ZielgruppeRolle, Vorwissen, Nutzungssituation
Scope / Nicht im ScopeSystem, Version, Umgebung sowie bewusste Ausschlüsse
Ownerverantwortliche Rolle oder Team; keine Sammeladresse ohne Zuständigkeit
Version / GültigkeitsstandProdukt-, API-, Prozess- oder Dokumentversion
StatusEntwurf, im technischen Review, freigegeben, veraltet oder archiviert
VoraussetzungenZugriff, Werkzeuge, Daten, Begriffe, Sicherheitsbedingungen
Ablaufnummerierte, einzeln prüfbare Schritte
Erwartetes Ergebnissichtbarer Zustand nach jedem kritischen Schritt
Beispielrealistischer, als Beispiel gekennzeichneter Fall
FehlerfälleSymptom, wahrscheinliche Ursache, sichere Maßnahme, Eskalation
Quellen und EntscheidungenPrimärquellen, ADRs, Tickets oder Spezifikationen
Fachlicher ReviewName oder Rolle, Datum und Ergebnis
Nächster Review / TriggerDatum und Ereignisse, die eine frühere Prüfung auslösen
Ausgefüllte Dokumentationsvorlage mit Owner, Version, Status und Review
Eine belastbare Vorlage verbindet Zuständigkeit und Gültigkeitsstand mit Ablauf, Nachweis, Fehlerfall und Review.

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.

Technical Documentation: in 8 Schritten erstellen

1. Scope und Erfolg festlegen

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.

2. Quellen sichern

Sammle Primärquellen: Code, Schnittstellenspezifikation, Produktentscheidung, Prozessbeschreibung und zuständige Fachperson. Trenne belegte Fakten von Annahmen und offenen Fragen.

3. Dokumenttyp wählen

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.

4. Informationsarchitektur bauen

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“.

5. Den Ablauf selbst ausführen

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.

6. Technisch und redaktionell prüfen

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.

7. Freigeben und auffindbar machen

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.

8. Pflege auslösen

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.

Ausgefülltes Beispiel: API-Schlüssel rotieren

Das folgende Beispiel ist fiktiv und redaktionell. Namen, Versionen und Zeiträume sind keine AFFiNE-Produktangaben.

FeldBeispielwert
ZweckEinen API-Schlüssel in Staging ersetzen, Erfolg prüfen und alten Schlüssel widerrufen
ZielgruppePlattformteam; Grundkenntnisse der Deployment-Konsole
OwnerPlatform Operations
Version / StatusDokument 1.3; freigegeben
Gültig fürAuth-Service 2.4; Staging; nicht Produktion
VoraussetzungenVier-Augen-Freigabe, Staging-Zugriff, Wartungsfenster von 30 Minuten
Schritteneuen Schlüssel erzeugen; Secret aktualisieren; Dienst neu laden; Testrequest prüfen; Logs 15 Minuten beobachten; alten Schlüssel widerrufen
ErfolgTestrequest liefert erwarteten Status; keine Auth-Fehler im Beobachtungsfenster
Fehlerfallbei steigender 401-Rate Rollback auf vorheriges Secret und Eskalation an den Bereitschaftsdienst
Reviewtechnisch 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.

Qualitätskriterien für brauchbare Dokumentation

Prüfe eine Seite nicht nach Textmenge, sondern nach Nutzung:

  • Auffindbar: Titel, Überschriften, Synonyme und Links passen zu den Begriffen der Zielgruppe.
  • Korrekt: Schritte, Beispiele und Systemstand wurden fachlich getestet.
  • Testbar: Kritische Schritte nennen ein erwartetes Ergebnis und eine sichere Reaktion bei Abweichung.
  • Konsistent: Gleiche Begriffe bedeuten dasselbe; Versionen und Querverweise widersprechen sich nicht.
  • Barrierearm: Struktur, Linktexte, Kontrast und Alt-Texte vermitteln den Inhalt auch ohne rein visuelle Hinweise. Die W3C WAI bündelt dafür die aktuellen Web-Zugänglichkeitsrichtlinien.
  • Aktuell: Owner, Review-Stand und Update-Trigger sind sichtbar.

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.

Review, Freigabe und Pflege als Lebenszyklus

Lebenszyklus von Planung über Schreiben und Review bis zur Pflege
Freigabe ist ein Zustand im Lebenszyklus; Änderungen und feste Review-Termine lösen die nächste Prüfung aus.

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:

  • Autor verantwortet Scope, Struktur und Quellen.
  • Fachreview prüft technische Richtigkeit und führt kritische Schritte aus.
  • Freigabe bestätigt Geltungsbereich und Veröffentlichungskanal.
  • Owner beobachtet Trigger, Feedback und veraltete Verweise.

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.

Technische Dokumentation, Wissensdatenbank, SOP oder PRD?

FormatHauptzweckTypischer InhaltAbgrenzung
technische DokumentationSystem oder technische Aufgabe verständlich machenAnleitung, Referenz, Architektur, Betriebkann mehrere Formate enthalten
Wissensdatenbankviele auffindbare Antworten organisierenverlinkte Artikel, Suche, Kategorienist der Container, nicht automatisch der Qualitätsprozess
SOPeinen wiederholbaren Prozess standardisierenRollen, Reihenfolge, Kontrollen, Nachweisenger und prozessorientierter
PRDProduktbedarf und gewünschtes Ergebnis beschreibenProblem, Nutzer, Anforderungen, Erfolgerklä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.

Technische Dokumentation mit AFFiNE organisieren

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:

  1. Schreibe Scope, Voraussetzungen, Ablauf und Quellen als strukturiertes Dokument.
  2. Zeichne Architektur, Datenfluss oder Fehlerpfad auf dem Whiteboard und halte Diagramm und Erklärung im selben Arbeitsbereich.
  3. Verlinke Entscheidungen, Projektnotizen und verwandte Anleitungen, statt Inhalte zu duplizieren. Die PARA-Methode kann helfen, aktive Projekte von dauerhaften Ressourcen zu trennen.
  4. Nutze eine Datenbank für Owner, Status, Version und Review-Datum, wenn mehrere Dokumente gepflegt werden.

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.

Häufige Fragen

Was gehört in eine technische Dokumentation?

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.

Welche Arten von Technical Documentation gibt es?

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.

Wie oft sollte technische Dokumentation geprüft werden?

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.

Wer sollte technische Dokumentation freigeben?

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.

Eignet sich AFFiNE für technische Dokumentation?

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.

Fazit: Dokumentation wird durch Verantwortung verlässlich

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