Technische Dokumentation: Ein vollständiger Leitfaden für Anfänger mit Beispielen

Wenn Ihr Produkt für den Einstieg ein wenig technisches Know-how erfordert, ist Ihre Dokumentation oft die erste und letzte Chance, diesen Benutzer als Kunden zu gewinnen.

Niemand möchte sich durch Ihre langweiligen tausenden Wörter voller Fachjargon quälen, sie wollen Ihr Produkt sofort nutzen.

Was mit technischer Dokumentation schwer zu erreichen ist, aber in den letzten fünfzehn Jahren der Erstellung von Tools für Kundenservice und Dokumentation haben wir genug gelernt, um Ihnen zu helfen, es möglich zu machen.

Eine technische Dokumentation, die leicht zu verstehen, zu überfliegen, zu durchsuchen ist und die die Konversionsrate verbessert.

In diesem Leitfaden werden wir alles über technische Dokumentation untersuchen: von den besten Beispielen über Schreibtipps bis hin zur Erstellung Ihrer eigenen.

Los geht's!

Was ist technische Dokumentation?

Technische Dokumentation ist eine Art von schriftlichem Material, das detaillierte Informationen darüber enthält, wie ein Produkt, eine Dienstleistung oder ein System verwendet, erstellt, gewartet und Fehler behoben werden können.

Zum Beispiel bezieht sich technische Dokumentation in der Softwareentwicklung auf einen Oberbegriff, der sich auf alle Anleitungen und anderen Inhalte bezieht, die mit der Entwicklung und den Funktionen bestimmter Produkte zusammenhängen.

Hier ist der Hauptunterschied zwischen normaler (oder allgemeiner) Dokumentation und technischer Dokumentation:

Normale Dokumentation	Technische Dokumentation
Bietet allgemeine Informationen in einfacherer Sprache.	Bietet tiefgehende Informationen, oft einschließlich technischer Begriffe, Code-Schnipsel, Diagramme und Beispiele.
Wird normalerweise erstellt, um einen schnellen Überblick über ein Produkt oder eine Dienstleistung in Form von Benutzerhandbüchern oder FAQs zu geben.	Enthält Anleitungen zur Verwendung, Erstellung, Wartung und Fehlerbehebung eines Produkts oder Systems. Einige Beispiele sind API-Dokumentation, Architekturhandbücher oder Systemdesign-Dokumente.
Entwickelt für Endbenutzer, Kunden oder Personen mit begrenzten technischen Kenntnissen.	Entwickelt für Entwickler, Ingenieure oder IT-Profis.

Warum ist technische Dokumentation wichtig?

Technische Dokumentation ist ein Asset, das verschiedenen Stakeholdern dient, indem es ihnen hilft, das Produkt und seine Entwicklung zu verstehen und auf dem gleichen Stand zu sein.

Und bietet gleichzeitig Kunden und Klienten eine Möglichkeit, Probleme mit einem Self-Help-Kanal zu lösen.

Technische Dokumentation ist entscheidend geworden, um erstklassigen Kundenservice zu bieten und gleichzeitig die Kosteneffizienz aufrechtzuerhalten.

Eine Studie von ThinkHDI¹ zeigt, dass Self-Help-Kanäle durchschnittlich nur 2,37 $ kosten, während Eins-zu-Eins-Kanäle durchschnittlich 15-37 $ kosten.

Hier sind einige weitere Vorteile technischer Dokumentation:

1. Verbessert die Kommunikation und Zusammenarbeit abteilungsübergreifend, indem sie als einzige Informationsquelle dient.
2. Steigert Effizienz und Produktivität
3. Verbessert die Kundenzufriedenheit durch Self-Service-Kanäle und schnelle Antworten.
4. Senkt die Kosten für den Kundenservice durch Reduzierung der Anzahl von Support-Tickets.
5. Verkürzt die Einarbeitungszeit und hilft neuen Mitarbeitern, schnell einsatzbereit zu sein.
6. Ermöglicht schnelle Entscheidungsfindung
7. Bietet eine Roadmap für zukünftige Projekte
8. Ideen aufzeichnen
9. Fördert die Wissensspeicherung

Arten der technischen Dokumentation

Technische Dokumentation kann in zwei Haupttypen unterteilt werden::

1. Produktdokumentation umfasst System- und Benutzerdokumentation.
2. Prozessdokumentation umfasst Prozess-Benchmarks und interne Abläufe

1. Produktdokumentation

Produktdokumentation enthält Informationen über das zu erstellende Produkt und gibt Anleitungen zu seinen Anwendungsfällen.

Diese Informationen umfassen Produktanforderungen, Geschäftslogik, technische Spezifikationen und Benutzerhandbücher.

Systemdokumentation

Systemdokumentation bietet einen Überblick über das Framework zur Produktentwicklung und ermöglicht es Produktentwicklern und anderen Beteiligten, die zugrunde liegende Technologie zu verstehen.

Typischerweise umfasst sie die Anforderungen, Spezifikationen, den Quellcode, das Architekturdesign, Validierungsberichte, Authentifizierungs- und Testdetails sowie Wartungsanweisungen.

Benutzerdokumentation

Benutzerdokumentation wird für diejenigen erstellt, die das Produkt verwenden. Die Arten von Benutzern können jedoch variieren. Deshalb müssen Sie diese Dokumente basierend auf verschiedenen Nutzungskategorien und Kenntnisständen erstellen.

Normalerweise richtet sich die Benutzerdokumentation an zwei Hauptsegmente: Systemadministratoren und Endbenutzer.

Diese Art von Dokumentation besteht aus Anleitungen, Benutzerhandbüchern, Installationsanleitungen, Fehlerbehebungsdokumenten, Bedienungsanleitungen, FAQs und Hilfshandbüchern.

2. Prozessdokumentation

Prozessdokumentation umfasst jedes Inhaltselement, das im Zusammenhang mit der Erstellung und Verwaltung von Prozessen im Produkt-Engineering erstellt wird.

Der Hauptunterschied zwischen Prozess- und Produktdokumentation besteht darin, dass erstere die technischen Verfahren dokumentiert, während letztere das Produkt erklärt.

Der Grund für die Pflege der Prozessdokumentation ist die Verbesserung der Organisation und Planung der technischen Phase.

Diese Art von Dokumentation erfordert Vorbereitung und Strategie vor Beginn des Prozesses und auch während der Erstellung des Produkts.

Typische Prozessdokumentation umfasst Standardbetriebsverfahren, Projektdokumentation, Prozess-Blueprints, Testtermine, White Papers, Besprechungsprotokolle und auch Unternehmenskommunikation.

Die besten Beispiele für technische Dokumentation, von denen Sie sich inspirieren lassen können

Hier sind einige Beispiele für gute technische Dokumentation und was man daraus lernen kann.

1. Stripe API-Dokumentation

Wenn Sie Entwickler fragen, welches Unternehmen die beste API-Dokumentation hat, ist die Antwort normalerweise dieselbe: Stripe.

Was Stripe’s Docs außergewöhnlich macht, ist nicht nur, dass sie vollständig sind. Es ist, dass sie von Entwicklern geschrieben zu sein scheinen, die das Produkt tatsächlich nutzen, nicht von technischen Redakteuren, die einer Vorlage folgen.

Stripe pflegt ein internes 20-seitiges API-Design-Dokument, dem jeder neue Endpunkt folgen muss (welches).

Sie haben die Qualität der Dokumentation in ihre technische Karriereleiter integriert. Diese Disziplin zeigt sich auf jeder Seite.

Was man aus Stripes Beispiel lernen kann:

• Drei-Spalten-Layout hält Navigation, Erklärung und Code gleichzeitig sichtbar.
• Standardmäßig lesbar, bei Bedarf technisch: Keine langen Einführungen. Parameter haben klare Typen, Standardwerte und Einschränkungen. Beispiele verwenden echte Werte anstelle von Platzhaltern.
• Codebeispiele in sieben Sprachen: cURL, Node, Python, PHP, Ruby, Java und .NET. Dies sind auch produktionsreife Beispiele.
• In die Dokumentation integrierte Testfunktion: Führen Sie API-Aufrufe direkt von der Referenzseite mit Ihrem Testschlüssel aus.
• Consistent URL structure and predictable patterns. Their technical document format follows a strict template:
  • Beschreibung (was der Endpunkt tut, wann er verwendet werden soll)
  • Endpunkt (HTTP-Methode + URL)
  • Authentifizierungsanforderungen
  • Parametertabelle (Pfad, Abfrage, Body)
  • Beispielanfrage und -antwort
  • Fehlercodes, die für diesen Endpunkt spezifisch sind
  • Beispiel-Code-Snippets
• Automatisch ausgefüllte API-Schlüssel: Wenn Sie angemeldet sind, werden Ihre Test-API-Schlüssel direkt in den Codebeispielen angezeigt, wodurch ein mühsamer manueller Schritt entfällt.
• Hover-Highlight-Interaktion: Wenn Sie mit der Maus über eine Beschreibung fahren, wird die entsprechende Codezeile hervorgehoben, sodass genau angezeigt wird, was jeder Parameter tut.

Worauf Sie achten sollten

Obwohl Stripes technische Dokumentation sehr gut ist, ist sie nicht etwas, das jeder nachbilden sollte.

Sie kann für Anfänger überwältigend sein. Die schiere Menge an Informationen kann einschüchternd wirken.

Zum Beispiel weiß ein Entwickler, der neu im Zahlungsverkehr ist, vielleicht nicht, wo er anfangen soll.

Stripe löst dies mit einem „Erste Schritte“-Bereich, aber es ist leicht zu übersehen, wenn man direkt in die API-Referenz eintaucht.

Außerdem gibt es keine eingebetteten Videoinhalte. Was die Zugänglichkeit für visuelle Lerner einschränkt.

2. Twilio-Dokumentation

Twilio steht vor einer einzigartigen Herausforderung. Ihre Produkte (SMS, Sprache, Video, E-Mail) sind konzeptionell einfach, haben aber viele Konfigurationsoptionen.

Ihre Dokumentation schafft ein Gleichgewicht zwischen der schnellen Erreichung eines funktionierenden Prototyps durch Entwickler und der Erklärung der vollen Plattformfähigkeiten.

Jedes ihrer Produkte verfügt über eine Schnellstartanleitung, eine API-Referenz und Codebeispiele in mehreren Sprachen. Das ist sinnvoll, da Twilio-Kunden oft wegen eines Produkts kommen und zu anderen wechseln, wenn ihre Bedürfnisse wachsen.

Was man aus Twilios Beispiel lernen kann:

• Schnellstarts, die tatsächlich in Minuten funktionieren: Die Anleitungen setzen keine Einrichtung voraus und führen Sie durch die Erstellung eines Kontos, den Erhalt von Anmeldeinformationen, die Installation des SDK und die Ausführung Ihres ersten API-Aufrufs. Die Anweisungen sind spezifisch genug, dass Sie ihnen folgen können, ohne andere Dokumente nachschlagen zu müssen.
• Codebeispiele in sechs oder mehr Sprachen
• Kontext vor Code: Bevor Sie die API-Parameter sehen, erklärt Twilio, wie programmierbare SMS funktionieren, welche Telefonnummern es in verschiedenen Ländern gibt und wie man zwischen Kurzcodes und Langcodes wählt. Dies hilft Entwicklern, fundierte Entscheidungen zu treffen, bevor sie Code schreiben.
• Migrationsleitfäden für gängige Übergänge
• Klare Trennung zwischen REST-API und Hilfsbibliotheken: Die SDK-Dokumentation wird separat gehalten, aber prominent verlinkt.
• Feedback-Widget für jeden Abschnitt. Was zur Verbesserung der Dokumentationsqualität beiträgt.

Worauf Sie achten sollten

Skalierung schafft Navigationsherausforderungen. Bei Tausenden von Seiten für Dutzende von Produkten kann es immer noch schwierig sein, den richtigen Ausgangspunkt zu finden.

3. Notion

Sie müssen es akzeptieren. Tools wie Notion (Tools mit Hunderten von Funktionen und Anwendungsfällen) erfordern einige technische Fähigkeiten, um das Beste daraus zu machen.

Wo die meisten Hilfezentren eher darauf ausgelegt zu sein scheinen, Support-Tickets abzuwehren, als den Benutzern wirklich zu helfen.

Notions Hilfezentrum verfolgt den entgegengesetzten Ansatz und behandelt die Dokumentation als Erweiterung des Produkterlebnisses selbst.

Notion organisiert seine Hilfeinhalte in drei verschiedene Ebenen:

• Referenzdokumente für schnelle Antworten auf spezifische Fragen
• Anleitungen für längere Tutorials, organisiert nach Teamfunktion (Entwicklung, Design, Marketing, Personalwesen),
• Notion Academy für strukturierte Kurse mit Quiz und Zertifizierungen.

Dieser dreistufige Ansatz ermöglicht es Benutzern, ihre Tiefe selbst zu wählen, und er funktioniert.

Was man aus Notions Beispiel lernen kann:

• Dreistufige Inhaltsarchitektur (Referenz, Anleitungen, Akademie) bedient verschiedene Lernstile und Dringlichkeitsstufen von einem einzigen Hilfezentrum aus.
• Benutzerdefinierte Illustrationen und visuelle Identität lassen das Hilfezentrum als Teil der gesamten Markenidentität von Notion erscheinen.
• Leitfäden, die nach Teamfunktion organisiert sind (nicht nur nach Produktmerkmalen), helfen Benutzern, Inhalte zu finden, die zu ihrem tatsächlichen Workflow und ihrer Rolle passen.
• In-App-KI-Integration, um das Help Center direkt im Arbeitsbereich abzufragen.

Worauf Sie achten sollten

Einige von Notions Leitfäden verwischen die Grenze zwischen Bildung und Marketing, insbesondere bei KI-Funktionen, was das Vertrauen skeptischer Leser untergraben kann.

4. Slack API

Öffnen Sie die Slack API-Dokumentation und das erste, was Ihnen auffällt, ist der Ton. „Hallo, lieber Entwickler!“ begrüßt Sie zusammen mit einem Wellen-Emoji, was den konversationellen Ton vorgibt, der sich auf der gesamten Website durchzieht. Es ist eine bewusste Entscheidung und sie funktioniert gut.

Slack hat Anfang 2025 eine große Dokumentationsmigration abgeschlossen. Die neue Architektur organisiert Inhalte in vier klare Kategorien:

• Leitfäden (konzeptionelle Erklärungen)
• Referenz (API-Methoden, Scopes, Events)
• Beispiele (ausführbare Apps)
• Tools (Bolt-Framework, SDKs, CLI)

Slacks explizites Ziel ist es, Anfängern unter den Entwicklern 15 Minuten von der Anmeldung bis zum ersten API-Aufruf zu ermöglichen. Dieses Ziel prägt jede Dokumentationsentscheidung, von der Platzierung von Quickstart-Links bis zum Design ihres interaktiven API-Testers.

Was Sie aus Slacks Beispiel lernen können:

• Konversationeller Ton mit Substanz beweist, dass man gleichzeitig freundlich und präzise sein kann, wodurch technische Inhalte zugänglicher werden, ohne an Genauigkeit zu verlieren.
• Interaktiver API-Tester, der in die Dokumentation integriert ist, ermöglicht es Entwicklern, Endpunkte direkt im Browser auszuprobieren.
• Block Kit Builder bietet eine visuelle Drag-and-Drop-Oberfläche zum Erstellen von UI-Komponenten mit Live-Vorschau und JSON-Ausgabe.
• Transparenter Changelog
• Entwickler-Sandbox: Kostenlose Sandbox-Umgebungen der Enterprise-Stufe über das Developer Program bieten Entwicklern einen risikofreien Testbereich.

Worauf Sie achten sollten:

• Plattformfragmentierung: Die Unterscheidung zwischen klassischen Apps, Slack-Apps, Workflow-Apps und Workflow Builder ist unklar. Das kann für neue Entwickler sehr verwirrend sein.
• Wiederholte Verlängerungen der Deprecation-Fristen (die Einstellung klassischer Apps wurde mehrmals verschoben) untergraben das Vertrauen der Entwickler in die Stabilität der Plattform.
• Dokumentation während der Migrationsperiode existierte gleichzeitig an zwei Orten, was zu Verwirrung darüber führte, welche Website kanonisch war.

5. GitHub-Dokumentation

Hier ist etwas Ungewöhnliches an GitHubs Dokumentation: Die Dokumentation selbst ist Open Source.

Das GitHub Docs Repository hat über 66.700 Forks erhalten und ist damit eines der meist-geforkten Dokumentationsprojekte überhaupt und ein funktionierendes Beispiel für Docs-as-Code, das in massivem Umfang praktiziert wird.

GitHub Docs deckt eine riesige Fläche ab, von Git-Grundlagen und Repository-Management bis hin zu GitHub Actions. Inhalte sind auf der Homepage in 10 Hauptkategorien mit einem Versionsselektor organisiert.

Die Verwaltung all dieser ist eine bedeutende technische Leistung.

Was Sie aus dem Beispiel von GitHub Docs lernen können:

• Community-gesteuerte Inhalte mit redaktioneller Aufsicht: Dies lädt zu Community-Beiträgen ein und schafft Vertrauen durch Transparenz.
• Single-Source-Versionierung dient der Dokumentation für acht gleichzeitige Produktversionen aus einem einzigen Dateisatz.
• Copilot-gestützte Suche generiert Antworten in natürlicher Sprache aus der Dokumentation.
• Praktische Anleitungen zur Fehlerbehebung

6. Ahrefs

Die Wissensdatenbank von Ahref ist nach seinen Funktionen gegliedert: Site Explorer, Keywords Explorer, Rank Tracker, Site Audit, Content Explorer und andere.

Jede Sammlung zeigt Autoren-Avatare und Artikelanzahlen, was ihr ein persönliches, teamorientiertes Gefühl verleiht.

Die Wissensdatenbank ist nur ein Teil des größeren Bildungsökosystems von Ahrefs und nicht einmal der beste Teil.

Die Ahrefs Academy bietet kostenlose strukturierte Videokurse (SEO-Grundlagen, Content-Marketing, Blogging für Unternehmen) mit Zertifizierung. Und der Blog Ahrefs Blog veröffentlicht datengesteuerte SEO-Anleitungen.

Das Help Center bearbeitet produktspezifische Fragen, während der Blog, die Academy und YouTube sich um breitere Bildung kümmern: Diese Arbeitsteilung ist eine nachahmenswerte Strategie.

Was man vom Beispiel Ahrefs lernen kann:

• Mehrstufiges Bildungsökosystem: Help Center für Produktfragen, Academy für strukturiertes Lernen, Blog für Vordenkerrolle, YouTube für visuelle Tutorials.
• Tool-zentrierte Organisation spiegelt die eigene Navigation des Produkts wider, sodass Benutzer intuitiv Artikel über die Funktion finden, die sie gerade verwenden.
• Artikel mit vielen Screenshots und Anmerkungen bieten kontextbezogene Anleitungen.
• FAQs auf der Homepage beantworten die häufigsten Fragen sofort und reduzieren die Suchreibung.
• Leistungsstarkes Chat-Widget ermöglicht es Benutzern, die Wissensdatenbank zu durchsuchen oder sich mit dem Support-Team zu verbinden.

Ahrefs ist das beste Beispiel dafür, wie man ein Bildungsökosystem rund um sein Produkt aufbaut. Ihre Blogbeiträge, die Academy und YouTube-Videos sind Teil ihrer Dokumentationsstrategie, die sich an verschiedene Zielgruppen richtet.

Wie man technische Dokumentation erstellt (Schritt-für-Schritt-Anleitung)

Schritt 1: Anforderungen und Art des zu erstellenden Inhalts festlegen

Denken Sie bei der Planung technischer Dokumentationen darüber nach, warum sie für Ihr Unternehmen nützlich sein kann, wie viel Dokumentation benötigt wird und ob es sich lohnt, Zeit und Geld in die Erstellung zu investieren?

Zu wenig technische Dokumentation kann die allgemeine Nützlichkeit beeinträchtigen. Andererseits verwirrt zu viel Information die Dinge für Sie.

Hier sind die Arten von Inhalten, die Sie mit Ihrer technischen Dokumentation planen können:

• Produktumfang und Planung
• Systemdokumentation
• Quellcode, API-Dokumentation
• Fehlerbehebungs- und Wartungshandbücher
• Änderungsprotokolle
• Anwendungsfälle
• Benutzerhandbücher
• Prozessdokumentation

Schritt 2: Technische Dokumentation schreiben

Die Nützlichkeit Ihrer technischen Dokumentation hängt von der Schreib- und Lehrqualität der Anleitungen ab, insbesondere wenn Sie sie zur Lösung von Kundenproblemen erstellen.

Hier sind einige Tipps zum Schreiben hochwertiger technischer Dokumente:

2.1. Schreiben Sie für Ihr Publikum

Das Verständnis des Publikums ist sehr wichtig. Zum Beispiel würde das Servieren von nicht-vegetarischem Essen für Vegetarier nicht funktionieren – oder?

Dasselbe gilt für jede Art von Dokumentation.

Sie müssen Ihre Lehrmethoden anpassen, je nachdem, für wen Sie schreiben.

Schauen wir uns das WordPress-Beispiel an:

Beispiel für eine kundenorientierte WordPress-Dokumentation.

Beispiel für technische WordPress-Dokumentation.

Der Unterschied hier?

Zielgruppe: Normale Dokumentation wird für Redakteure, Blogger, Manager oder Personen ohne technisches Wissen erstellt.

Während technische Dokumentation für Entwickler, Ingenieure, Serverbetreiber oder technische Benutzer erstellt wird.

Inhaltlicher Unterschied: Normale Dokumentation ist sehr einfach, direkt auf den Punkt gebracht und enthält keine technischen Details.

Während technische Dokumentation viele Informationen, verlinkte Ressourcen, Code und reale Beispiele dafür enthält, wie jemand bestimmte Funktionen oder Parameter verwenden kann.

Erforderliche Erfahrung: Die normale Dokumentation kann von jedem mit Schreibfähigkeiten und etwas Produktrecherche erstellt werden, während technische Dokumentation die Beteiligung eines Entwicklers oder Experten erfordert, um korrekt und nützlich zu sein.

2.2. Produkt, Code oder Forschung gründlich testen

Dokumentation wird erstellt, um Kunden zu helfen oder um ein besseres Verständnis der Situation zu erlangen.

Normalerweise wird kundenorientierte Dokumentation von einem Dokumentationsautor, Kundendienstmitarbeitern oder einem Autor erstellt. Und es funktioniert.

Aber bei der technischen Dokumentation ist das nicht dasselbe. Sie benötigen mehr als nur Produkt- oder Codeverständnis.

Einblicke, die nur durch richtige Beteiligung und Tests gewonnen werden können.

2.3. Mit einer Gliederung beginnen

Das Erstellen einer Gliederung vor jedem Leitfaden oder Tutorial dauert nicht lange (normalerweise 1 Stunde), kann aber in späteren Phasen der Inhaltserstellung viel Zeit sparen.

Haben Sie sich jemals gefragt, warum Ihre Artikel/Anleitungen nicht gut klingen, funktionieren oder diese professionelle Ausstrahlung haben?

Weil sie nicht gut geplant waren.

Hier sind einige Dinge, die Sie mit den Gliederungen Ihrer technischen Dokumente abdecken können:

1. Titel
2. Ziel-Keywords oder die gebräuchlichsten Suchbegriffe
3. User Stories (Als Benutzer möchte ich, damit-Formel)
4. Zielgruppe, für wen es ist
5. Artikeltyp: How-to, Listicles, Video, Rezension oder Vergleich zum Beispiel.
6. Ziele
7. Referenzartikel
8. Erwartete Wortanzahl
9. Kurze Gliederung (oder Inhaltsverzeichnis): Umfang dessen, was Sie abdecken werden, vorhandene Ressourcen und Artikelstruktur.

2.4. Halten Sie es einfach (verwenden Sie Vorlagen) und fügen Sie keinen unnötigen Ballast hinzu

Das Hinzufügen von nur notwendigen Informationen sollte einer der Hauptpunkte in Ihrem Schreibstil-Leitfaden für technische Dokumentation sein.

Außerdem können Sie basierend auf Ihrer Erfahrung und Ihren Tests Vorlagen (Artikeltyp-Vorlagen) erstellen, die für die Art der von Ihnen erstellten Inhalte am besten geeignet sind.

1. Vermeiden Sie die Verwendung von Fachbegriffen und erklären Sie diese, wenn Sie sie absolut nicht vermeiden können.
2. Halten Sie Absätze kurz.
3. Gliedern Sie Inhalte mit Überschriften, Unterüberschriften, Listen, Tabellen und Bildern auf.
4. Vermeiden Sie übermäßige Erklärungen und entfernen Sie so viel wie möglich unnötige Inhalte.

2.5. Visuelle Hilfsmittel verwenden

Visuelle Elemente machen einen Unterschied, insbesondere wenn sie technische Konzepte leicht verständlich machen.

Es kann ein einfacher Screenshot, eine Skizze, eine Zeichnung oder eine gut gestaltete Grafik sein. Solange es hilft!

2.6. Beispiele und Referenzen hinzufügen, wann immer möglich

Technische Dokumentation befasst sich mit der Dokumentation und Aufschlüsselung komplexer Informationen.

Das Hinzufügen von Beispielen und das Verlinken relevanter Ressourcen, wann immer möglich, hilft dabei.

Sie können Beispiele hinzufügen, um Folgendes zu zeigen:

• Code-Verwendung (wie eine bestimmte Funktion oder ein Parameter verwendet werden kann)
• Produkt- oder Softwareanwendungsfälle. Insbesondere wenn es mehrere Möglichkeiten gibt.
• Wie eine bestimmte Sache oder Funktion implementiert wurde oder wie ein Wettbewerber es gemacht hat.

2.7. Überprüfen lassen

Beziehen Sie Entwickler, Ingenieure und Teammitglieder in den Dokumentationsprozess ein, um ein besseres Verständnis der Lösung zu erhalten.

Das Erstellen technischer Artikel erfordert die kollektive Beteiligung aller Gruppenmitglieder.

Sobald Sie einige technische Beiträge vorbereitet haben, zeigen Sie sie Ihren Kollegen und holen Sie deren Meinungen ein.

Um die Dinge zu vereinfachen, verwenden Sie Kollaborationssoftware wie Kanban-Boards, Slack und Google Docs.

2.8. Erstellen Sie einen Styleguide für technische Texte

Wenn Sie mit der Erstellung Ihrer technischen Inhalte beginnen, erstellen Sie einen Styleguide, der für Sie am besten funktioniert.

Er hilft, Wissen zu bewahren, Konsistenz zu schaffen und die Qualität der Inhalte aufrechtzuerhalten.

Zum Beispiel kann Ihr Styleguide Folgendes enthalten:

1. Zielgruppenprofil oder Zielgruppe
2. Schreibstil und Ton
3. Grammatik- und Nutzungsregeln
4. Formatierungsrichtlinien Terminologie
5. Dokumentenstruktur
6. Visuelle Richtlinien
7. Barrierefreiheitsstandards
8. Richtlinien für Links und externe Verweise
9. Überprüfungs- und Genehmigungsprozess
10. Werkzeuge und Ressourcen

Wir haben in unserem Knowledge Base Style Guide viel über Styleguides gesprochen, der Ihnen einen guten Ausgangspunkt bietet.

Schritt 3: Erstellung einer technischen Dokumentationswebsite

🤯, ich weiß, ich weiß.

Wenn Sie dem Leitfaden bisher gefolgt sind, ist das viel zu verarbeiten. Aber ich empfehle dringend, etwas Zeit zu investieren, um Ihre Inhalte zusammenzustellen.

Denn das wird Ihre technische Dokumentation für Sie und Ihre Benutzer normal machen, nicht technisch.

Denken Sie daran, dass Sie nicht von Anfang an das Beste anstreben müssen, da Erfahrung, Tests und Feedback viel dazu beitragen, etwas Nützliches zu schaffen.

Ständige Verbesserung ist hier der Schlüssel. Jetzt benötigen wir eine Website oder eine Plattform, um erstellte Inhalte zu veröffentlichen.

3.1. WordPress-Website erstellen

Wir erstellen eine dedizierte technische Dokumentationswebsite oder ein Portal, auf dem Sie alle Ihre privaten und öffentlichen Dokumente hosten und pflegen können.

Warum eine Website für Dokumentation erstellen?

1. Benutzerdefiniertes Branding
2. Bessere Benutzererfahrung
3. Zentralisierter Zugriff
4. Erweiterte Funktionen wie Integration, Analysen, Versionskontrolle und -verwaltung.
5. Vollständige Kontrolle

Ich empfehle dringend WordPress mit Heroic Knowledge Base (Heroic KB) für die Dokumentationswebsite, und das werden wir für dieses Tutorial verwenden.

WordPress ist kostenlos, Open Source und die beliebteste CMS-Plattform für die Dokumentation.

Während Heroic KB ein Premium-WordPress-Plugin ist, um jede Art von Dokumentationswebsite zu erstellen.

Wenn Sie eine kostenlose Lösung wünschen und über ein Entwicklungsbudget oder -fähigkeiten verfügen, können Sie Lösungen wie MkDocs verwenden.

Um eine WordPress-Website zu erstellen, können Sie sie auf jeder Art von Hosting-Service installieren (einschließlich Webhosting, Cloud-Hosting und dedizierten Servern).

Um die Dinge einfach zu halten, verwenden Sie verwaltete WordPress-Hosting-Plattformen wie Kinsta.

Überprüfen Sie außerdem dieses Tutorial, wenn Sie planen, WordPress manuell zu installieren, oder bitten Sie einfach Ihren Hosting-Anbieter, WordPress für Sie zu installieren.

3.2. Dokumentations-Website erstellen

Jetzt, da Sie eine WordPress-Site eingerichtet haben, installieren Sie das Heroic KB-Plugin, um die für Ihr Dokumentationsportal benötigten Funktionen zu erhalten.

Laden Sie das Heroic KB-Plugin herunter, indem Sie es hier kaufen.

1. Gehen Sie zum WordPress Dashboard (das Sie erreichen, indem Sie /wp-admin am Ende Ihrer Website-URL hinzufügen)
2. Klicken oder fahren Sie mit der Maus über Plugins → Neues Plugin hinzufügen.
3. Klicken Sie auf die Schaltfläche Plugin hochladen.
4. Wählen Sie eine heruntergeladene Heroic KB-Plugin-Datei.
5. Klicken Sie auf die Schaltfläche Jetzt installieren.
6. Klicken Sie nach der Installation auf Plugin aktivieren.

Sobald das Plugin aktiviert ist, wird Ihnen ein Heroic Knowledge Base Setup-Assistent angezeigt.

Folgen Sie den Anweisungen, um die Demo-Website wie hier gezeigt zu importieren: https://heroickb.herothemes.com/

Hinweis: Sie können den Setup-Assistenten über den Plugin-Bereich aufrufen, wenn Sie ihn während des Installationsvorgangs nicht abgeschlossen haben.

Ihre Dokumentationswebsite ist zu diesem Zeitpunkt fertig und Sie können sie im Frontend unter ihredomain.com/knowledge-base/ aufrufen.

3.3. Benutzerzugriff und Rollen

Mit WordPress und Heroic KB haben Sie alle notwendigen Optionen, um Benutzerzugriff und Rollen zu verwalten. So können Sie interne oder öffentlich zugängliche Dokumentationen erstellen.

Benutzer können über WordPress → Benutzer verwaltet werden. Sie können neue Benutzer manuell hinzufügen oder eine WordPress-Option aktivieren, um die Registrierung neuer Benutzer zu ermöglichen.

Aktualisieren Sie die Heroic KB-Einstellungen, um die Dokumentation nur für den internen Gebrauch zu machen, oder Sie haben die Option, jeden Artikel als intern oder öffentlich zu kennzeichnen.

WordPress → Heroic KB → Einstellungen

3.4. Anpassung

Mit technischer Dokumentationssoftware wie Heroic KB haben Sie alle Optionen, die Sie benötigen, um die Dokumentation an Ihren Markenstil oder Ihre Vorlieben anzupassen.

Alle Einstellungen können unter WordPress → Heroic KB → Einstellungen aufgerufen werden.

Zum Beispiel, um das Farbschema der Dokumentation zu aktualisieren:

Zum Aktualisieren der Layout-Einstellungen:

Weitere Anpassungen können mit WordPress-Themes oder benutzerdefiniertem Code vorgenommen werden.

Mit einem Heroic KB-Kauf erhalten Sie ein Premium-Theme Heroic KnowAll, das unbegrenzte Anpassungsmöglichkeiten freischaltet, ohne eine einzige Zeile Code schreiben zu müssen.

Schritt 4: Veröffentlichung und Verwaltung von Dokumenten

Jetzt, da wir Inhalte und ein Portal bereit haben, müssen Sie nur noch Ihre Inhalte hinzufügen und veröffentlichen.

Sie können alle Ihre Artikel, Kategorien und Schlagwörter unter WordPress → Heroic KB verwalten.

Um einen neuen Artikel hinzuzufügen, klicken oder fahren Sie mit der Maus über Heroic KB → Neuen Artikel hinzufügen.

Und so sieht Ihr Artikel-Builder-Bildschirm aus:

Es ist ein sehr einfach zu bedienender und flexibler Editor, sobald Sie sich daran gewöhnt haben.

Außerdem erhalten Sie zusätzliche Blöcke von Heroic KB, um einfach ein Inhaltsverzeichnis, Toggles, Akkordeons, Tabs, Codeblöcke zu erstellen oder wichtige Informationen zu teilen.

Das gesamte Styling kann über WordPress-Themes oder über kundenspezifischen Code verwaltet werden.

Schritt 5: Weiter optimieren

Die Erstellung technischer Dokumentationen endet nicht mit der Veröffentlichung von Inhalten.

Es ist ein kontinuierlicher Verbesserungsprozess, bei dem Dokumentationen genutzt werden, um das Wissen Ihres Unternehmens aufzubauen, die Neuerfindung des Rades zu vermeiden und Prozesse zu optimieren.

Hier sind einige Tipps, wie Sie Ihre technische Dokumentation optimieren können:

1. Optimieren Sie die Erstellung und Verwaltung von Inhalten
2. Erstellen und verbessern Sie Richtlinien für technische Dokumentationen basierend auf Benutzerfeedback
3. Stellen Sie eine einfache Navigation und einen einfachen Zugriff auf die Dokumentation sicher
4. SEO-Optimierung
5. Führen Sie häufige Backups durch

Heroic KB und WordPress verfügen über integrierte Funktionen zur Verbesserung der Dokumentation.

Funktionen wie leistungsstarke Analysen, Feedbacksystem, SEO-freundliche Website-Struktur und Integrationen, redaktionelle Optionen und Revisionskontrolle.

Tools und Software für technische Dokumentation zur Unterstützung

Ich werde hier kurz sein, da wir bereits sehr detaillierte Anleitungen zu Technical Documentation Tools und Technical Writing Tools haben.

Diese empfohlenen Tools werden Ihnen bei der Erstellung, Verwaltung und Optimierung technischer Dokumentationen erheblich helfen.

1. WordPress + Heroic KB

Heroic KB ist ein beliebtes, preiswertes und kollaboratives System für technische Dokumentation. Es eignet sich für eine breite Palette von Branchen und Produkten.

Dies erfüllt problemlos die meisten Anforderungen an Ihre technische Dokumentation.

2. Mammoth .docx converter

Ein WordPress-Plugin, mit dem Sie Dokumente einfach importieren können, um Beiträge und Seiten zu erstellen.

Vervollständigen Sie Ihren Artikel mit Google Docs und veröffentlichen Sie ihn mit WordPress in nur unter 5 Minuten mit diesem Tool. So einfach ist es, Inhalte mit WordPress zu veröffentlichen.

3. Github

Wahrscheinlich kennen Sie dieses bereits. Sie können es auch für technische Dokumentation nutzen. Es verfügt über eine eigene Wiki-Plattform, die sich gut für 5-20 Dokumentationsstücke eignet.

4. Figma

Es ist eine webbasierte Designsoftware, die einfach zu bedienen und sehr flexibel ist.

Ähnlich wie WordPress verfügt es über unzählige Plugins zur Erweiterung seiner Funktionalität, Vorlagen zur schnellen grafischen Erstellung und Kollaborationsfunktionen. Es ist eines der besten kostenlosen Tools, die es gibt. Probieren Sie es aus!

5. Google Docs

Sie benötigen eine einfache Möglichkeit, Inhalte zu erstellen und gleichzeitig mit dem Team zusammenzuarbeiten, und Google Docs ist dafür am besten geeignet.

6. FastStone Capture

Ein Premium-Tool zum Erfassen und Aufzeichnen von Bildschirmen. Sie können Bilder mit Anmerkungen versehen und sie mit anderen erstaunlichen Funktionen bearbeiten. Es wird mit einer lebenslangen Lizenz geliefert, die sich absolut lohnt!

7. MkDocs

Eine großartige Plattform, um kostenlos statische Websites für technische Dokumentation zu erstellen. Sie verfügt über viele gute Themes und Plugins zur Verbesserung des Gesamterscheinungsbilds und der Funktionalität, erfordert jedoch Entwicklungskenntnisse.

Häufig gestellte Fragen zur technischen Dokumentation

Hier sind unsere am häufigsten gestellten Fragen zur technischen Dokumentation, zusammen mit ihren Antworten.

Was ist der Zweck der technischen Dokumentation?

Der Zweck der technischen Dokumentation besteht darin, Informationen über ein Produkt, ein System oder eine Dienstleistung bereitzustellen, die von einem technischen oder nicht-technischen Publikum verwendet werden. Diese Dokumentation hilft Benutzern zu verstehen, wie das Produkt funktioniert, wie es installiert, verwendet und Fehler behoben werden können und wie Teile bei Bedarf repariert oder ersetzt werden können.

Technische Dokumentation dient auch als Referenz für Ingenieure, Entwickler und andere Fachleute, die an dem Produkt arbeiten. Sie trägt dazu bei, Konsistenz und Standardisierung zu gewährleisten und einen historischen Überblick über die Entwicklung und Evolution des Produkts zu geben.

Wie organisiert und strukturiert man technische Dokumentation?

Hier sind einige Best Practices für die Organisation und Strukturierung technischer Dokumentation:

• Beginnen Sie mit einem Inhaltsverzeichnis oder einem Index, um einen Überblick über die behandelten Themen zu geben.
• Teilen Sie die Dokumentation in klare Abschnitte ein und verwenden Sie Überschriften und Unterüberschriften, um den Leser zu leiten.
• Verwenden Sie eine klare, prägnante Sprache und vermeiden Sie Fachjargon, es sei denn, er ist unvermeidlich und wird gründlich erklärt.
• Fügen Sie Beispiele und visuelle Hilfsmittel wie Diagramme und Screenshots hinzu, um komplexe Konzepte zu veranschaulichen.
• Verwenden Sie durchgängig ein konsistentes Format und einen konsistenten Stil für die Dokumentation, einschließlich Schriftgröße und -stil, Überschriften und Absatzabständen.
• Stellen Sie eine Suchfunktion oder einen Index für eine einfache Navigation bereit, insbesondere für längere Dokumentationssätze.

Was ist der Unterschied zwischen technischer Dokumentation und Benutzerdokumentation?

Technische Dokumentation und Benutzerdokumentation sind beides Formen schriftlicher Dokumentation, die Informationen über ein Produkt oder eine Dienstleistung liefern. Sie haben jedoch unterschiedliche Zwecke und Zielgruppen.

Technische Dokumentation richtet sich an technische Benutzer wie Ingenieure, Entwickler und IT-Profis. Sie liefert detaillierte Informationen über das Design, die Architektur und die technischen Spezifikationen des Produkts und wird zur Fehlerbehebung und Wartung verwendet.

Benutzerdokumentation hingegen richtet sich an Endbenutzer, wie Kunden und Mitarbeiter, die das Produkt oder die Dienstleistung nutzen. Sie liefert Informationen zur Verwendung des Produkts, einschließlich Schritt-für-Schritt-Anleitungen und visueller Hilfsmittel.

Zusammenfassung

Technisches Wissen ist ein wesentlicher Vermögenswert für Leser. Sie müssen nützliche technische Artikel für alle entwickeln und veröffentlichen, einschließlich Dokumente für Softwareentwickler und das Testteam sowie Benutzerdokumentation.

Doch aufgrund der schnellen Produktentwicklungszyklen kann es schwierig sein, Ihre technische Dokumentation verfügbar und ansprechend zu gestalten.

Ein gründliches technisches Wissensportal ist präzise, auf den Punkt gebracht und relevant. Und hier kann ein technisches Dokumentationsmanagementsystem wie Heroic KB helfen.

Mit den Content-Management- und Teamwork-Funktionen von Heroic KB können Sie Ihren Autorenpflegeprozess und Ihre technischen Anleitungen einfach verbessern. Und steigern Sie die Produktivität und das Benutzerengagement Ihrer Organisation.

In diesem Tutorial erwähnte Ressourcen

1. Verständnis der Service-Desk-Metrik Kosten pro Ticket von ThinkHDI ↩︎