So erstellen Sie eine technische Dokumentation im Jahr 2025 – Eine einfache Anleitung

Was ist technische Dokumentation?

Technische Dokumentation beschreibt, was ein Produkt kann. Sie wird hauptsächlich von Softwareentwicklungs- und Produktteams erstellt und hilft verschiedenen Teilen eines Unternehmens, das Produkt zu unterstützen.

Technische Dokumentation ist ein weit gefasster Begriff. Er bezieht sich auf alles, von Ihrem ersten PRD bis zu Ihren API-Dokumenten für andere Hersteller. Definieren wir ihn etwas genauer.

Verschiedene Arten von technischer Dokumentation – was ist enthalten und was nicht

10 gängige Arten von Dokumenten, die als technische Dokumentation gelten, sind:

1. Benutzerhandbücher

Dies sind Broschüren oder Online-Anleitungen, die Ihnen zeigen, wie Sie etwas verwenden, z. B. eine Kamera oder Software. Sie sind voll von Schritt-für-Schritt-Anleitungen.

• Wer verwendet sie: Jeder, der herausfinden möchte, wie man ein Produkt verwendet
• Wann sie erstellt werden: Nachdem das Produkt hergestellt wurde, aber bevor es verkauft wird

2. API-Dokumentation

Diese Dokumente erklären, wie Computerprogramme miteinander kommunizieren können. Wenn Sie eine App entwickeln, erfahren Sie hier, wie Sie sie mit anderer Software verbinden.

• Wer verwendet sie: Programmierer und App-Entwickler
• Wann sie erstellt wird: Während das Tool für Programmierer erstellt wird oder direkt danach

3. Handbücher für Systemadministratoren

Dies ist ein Handbuch für die technischen Fachleute, die Computersysteme einrichten, reparieren und sicherstellen, dass sie reibungslos laufen.

• Wer verwendet sie: Technischer Support und IT-Mitarbeiter
• Wann sie erstellt wird: Nachdem das Computersystem betriebsbereit ist

4. Installationsanleitungen

Diese Anleitungen geben Ihnen die Schritte, um eine Software oder Hardware zum Laufen zu bringen.

• Wer verwendet sie: Jeder, der neue Technologie einrichtet, von alltäglichen Benutzern bis hin zu IT-Mitarbeitern
• Wann sie erstellt wird: Nach der Herstellung des Produkts, aber bevor es auf den Markt kommt

5. Anleitungen zur Fehlerbehebung

Haben Sie ein Problem mit Ihrer Technologie? Diese Anleitungen helfen Ihnen herauszufinden, was falsch ist und wie Sie es beheben können.

• Wer verwendet sie: Benutzer mit Problemen, Helpdesks, IT-Experten
• Wann sie erstellt wird: Nachdem das Produkt auf dem Markt ist, mit Updates, wenn neue Probleme auftauchen

6. Whitepapers

Stellen Sie sich diese als tiefe Einblicke in ein bestimmtes technisches Thema vor, die Lösungen für technische Herausforderungen bieten oder erklären, wie ein Produkt helfen kann.

• Wer verwendet sie: Entscheidungsträger und Experten, die detaillierte Informationen suchen
• Wann sie erstellt wird: Jederzeit, oft um die Vorteile eines Produkts oder einer Technologie zu erklären

7. Versionshinweise

Wenn Software ein Update erhält, informieren Sie die Versionshinweise darüber, was neu ist, was besser ist und welche Probleme noch bestehen.

• Wer verwendet sie: Jeder, der die Software verwendet
• Wann sie erstellt wird: Zusammen mit Software-Updates

8. Produktdokumentation

Sie benötigen viel Schriftverkehr, um Ihre Produktentwicklung zu rationalisieren. Und alle Ihre Projektpläne sind Teil der technischen Dokumentation. Diese detaillierte Liste zeigt Ihnen genau, was ein Produkt kann und welche Funktionen es hat.

• Wer verwendet sie: Produktmanager und andere Teammitglieder sind in der Regel die Vorreiter.
• Wann sie erstellt wird: Zu Beginn der Herstellung eines Produkts

9. FAQs (Häufig gestellte Fragen)

Hier finden Sie Antworten auf häufige Fragen zur Verwendung eines Produkts oder einer Dienstleistung.

• Wer verwendet sie: Kundensupport-Teams und Benutzer, die schnelle Antworten suchen
• Wann sie erstellt wird: Beginnt mit den am häufigsten gestellten Fragen in Demo-/Discovery-Anrufen. Sie wird erweitert, indem die wahrscheinlichsten Fragen hinzugefügt werden, die andere Personen stellen werden. FAQs sind in hohem Maße von Ihrem ICP, seinen Journey-Meilensteinen usw. abhängig.

Diese beginnen klein und entwickeln sich mit der Zeit weiter, wie die meisten Benutzerdokumentationen. Wenn sich Ihr Produkt und Ihr ICP weiterentwickeln, ändern sich auch die FAQs. Technische Redakteure sind in der Regel diejenigen, die dies übernehmen.

10. Entwicklerhandbücher

Diese Anleitungen sind für die Programmierer gedacht und geben ihnen die Details zur Verwendung einer Technologie oder zur Arbeit mit einem Programmierwerkzeug.

• Wer verwendet sie: Programmierer und Softwareentwickler
• Wann sie erstellt wird: Während der Erstellung der Technologie und Aktualisierung bei Änderungen

Wer verwendet also technische Dokumentation?

Technische Dokumentation wird von internen Entwicklern, IT-Mitarbeitern, CXOs, PMs, CS-Teams, Endbenutzern und externen Entwicklern verwendet.

Und was ist KEINE technische Dokumentation?

Manchmal verwechseln die Leute einige Dokumente und halten sie für technische Anleitungen, obwohl sie es nicht sind. Während einiges davon – wie Ihr HR-Handbuch – offensichtlich nicht-technische Dokumentation ist, fallen einige Dokumente in einen Graubereich. Hier ist ein kurzer Überblick:

• Marketingmaterialien: Dinge wie Broschüren und Websites, die möglicherweise technisches Fachjargon verwenden, aber eigentlich versuchen, Sie zum Kauf zu bewegen. Sie sind nicht dazu da, Ihnen beizubringen, wie Sie das Produkt verwenden oder reparieren.
• Geschäftspläne und Berichte: Diese Papiere sprechen über die technische Seite eines Unternehmens oder neue Produktideen, aber es geht hauptsächlich darum, Pläne zu machen, zukünftiges Geld zu schätzen und den Markt zu prüfen.
• Interne Richtlinien und Verfahren: Wichtig für die Führung eines Unternehmens, aber es geht mehr um Regeln, richtiges Handeln und was Mitarbeiter tun sollten, nicht darum, wie man technische Dinge benutzt.
• Technische Vorschläge: Sie schlagen neue technische Projekte oder Lösungen vor und sprechen über die guten Dinge, die daraus entstehen können, ob es möglich ist und wie viel es kosten könnte, anstatt Schritt-für-Schritt-Anleitungen.
• User Stories und Use Cases: Wird viel bei der Softwareentwicklung verwendet, um zu erklären, was eine Funktion aus der Sicht eines Benutzers tun soll. Sie helfen herauszufinden, was Benutzer brauchen, sind aber keine detaillierten technischen Anweisungen. Verstehen Sie uns nicht falsch, User Stories und Use Cases helfen Teams bei der Entscheidung, was als Nächstes gebaut werden soll. Aber es zählt immer noch Marktforschung, nicht technische Dokumentation.

Zusammenfassend hier eine praktische Liste, was ist technische Dokumentation und was nicht ist:

‍

So erstellen Sie eine technische Dokumentation

Schritt 0: Legen Sie Ihren technischen Schreibstil-Leitfaden fest

Ihr technischer Schreibstil-Leitfaden hilft allen Mitwirkenden, einen einheitlichen Ton und eine einheitliche Vision für das Schreiben beizubehalten. Das beste Beispiel ist der Apple Style Guide. Die beliebte Marke arbeitet hart daran, überall einen ähnlichen Schreibstil beizubehalten.

Und das sollten Sie auch.

Auch wenn es jetzt keine Rolle spielt, wird es in einigen Monaten eine Rolle spielen, wenn Ihr Team und Ihre Benutzerbasis wachsen. Dazu gehört die Definition von Schriftarten bis hin zu Schritt-für-Schritt-Anleitungen für die Dokumentenerstellung und Workflow-Details.

Schritt 1: Finden Sie heraus, was Sie jetzt

Sie brauchen nicht alle 10 Arten von Dokumentation sofort. Unterschiedliche Bedürfnisse entwickeln sich und kommen während Ihres Entwicklungszyklus auf:

1. Tag 0 bis Tag 30: Ideenfindungsphase

• Produktspezifikationen: Beginnen Sie mit der Kernidee Ihres Produkts. Skizzieren Sie Funktionen, Fähigkeiten und Benutzerbedürfnisse.

2. Monat 1 bis Monat 6: Entwicklungsphase

• API-Dokumentation: Wenn Ihr Produkt APIs enthält, beginnen Sie mit dem Entwurf der Dokumentation, während die Entwicklung fortschreitet.
• Entwicklerhandbücher: Beginnen Sie mit der Arbeit an Anleitungen, wenn sich Ihr Produkt an Entwickler richtet, und aktualisieren Sie diese, sobald die Funktionen fertiggestellt sind.
• Technische Vorschläge: Verfeinern Sie diese Dokumente weiter, wenn Anpassungen aufgrund von Feedback von Stakeholdern oder sich änderndem Projektumfang erforderlich sind.

3. Monat 7 bis 12: Vorbereitungsphase für die Markteinführung

• Handbücher für Systemadministratoren: Beginnen Sie mit dem Entwurf, sobald die Systemarchitektur feststeht.
• Installationsanleitungen: Entwerfen Sie diese Anleitungen, sobald der Installationsprozess definiert ist.
• Benutzerhandbücher und Anleitungen zur Fehlerbehebung: Skizzieren und entwerfen Sie Benutzerhandbücher basierend auf den entwickelten Funktionen und den erwarteten häufigen Problemen.
• FAQs (Häufig gestellte Fragen): Stellen Sie Fragen zusammen, die auf Beta-Tests oder erwarteten Benutzeranfragen basieren.
• Versionshinweise: Bereiten Sie sich auf die erste Markteinführung vor und beschreiben Sie Funktionen, Fehlerbehebungen und bekannte Probleme.

4. Monat 13 bis 24: Phase nach der Markteinführung und Wachstumsphase

• Aktualisieren Sie alle vorherigen Dokumentationen: Spiegeln Sie Änderungen, Aktualisierungen und Feedback aus der realen Nutzung wider.
• Kontinuierliche Aktualisierungen:
• Produktspezifikationen: Aktualisieren Sie sie, wenn neue Funktionen hinzugefügt werden oder sich das Produkt wesentlich ändert.
• API-Dokumentation und Entwicklerhandbücher: Halten Sie diese Dokumente auf dem neuesten Stand, um das Engagement der Entwickler und die Benutzerfreundlichkeit zu fördern.
• Handbücher für Systemadministratoren und Installationsanleitungen: Überarbeiten Sie sie basierend auf Software-Updates oder Änderungen der Systemanforderungen.
• Benutzerhandbücher und Anleitungen zur Fehlerbehebung: Aktualisieren Sie diese Dokumente regelmäßig, um neue Lösungen zu integrieren und zusätzliche Benutzerfragen zu beantworten.
• FAQs: Fügen Sie kontinuierlich neue Fragen hinzu, wenn Benutzer mehr mit dem Produkt interagieren.
• Versionshinweise: Stellen Sie mit jeder neuen Version oder jedem neuen Update detaillierte Versionshinweise bereit, um Benutzer über Änderungen zu informieren.

Wie Sie sehen, haben Sie möglicherweise nur verschiedene Iterationen Ihres PRD, wenn Sie gerade erst mit der Entwicklung Ihres Produkts begonnen haben. Wenn Sie jedoch bereits auf den Markt gekommen sind und sich in der Wachstumsphase befinden, haben Sie höchstwahrscheinlich bereits alle Arten von technischer Dokumentation erstellt, aber sie ist möglicherweise verstreut.

Erstellen Sie basierend darauf einen neuen Arbeitsbereich in Slite und erstellen Sie verschiedene Kanäle/Seiten nur für die Art von Dokumentation, die Sie haben/benötigen. Falls Sie nach unserer Vorlage suchen, kopieren Sie sie direkt in Ihren Slite-Arbeitsbereich hier.

Schritt 2: Sammeln Sie Ihre vorhandenen Dokumente an einem Ort.

Sobald Sie Ihre Homebase strukturiert haben, haben Sie ein klares Bild von der gesamten Dokumentation, die Sie in dieser Phase haben sollten.

Da Sie möglicherweise bereits einiges davon haben, beginnen Sie mit dem Import aus anderen Quellen. Anstatt auf eine leere Seite zu starren, beginnen Sie mit dem Import der Dokumentation, die Sie bereits haben. Im Moment können dies lose Besprechungsnotizen, Produkt-Roadmaps oder PRDs aus Ihren Brainstorming-Anrufen sein. Normalerweise wird diese Art von Dokumentation in Besprechungen als schnell erstellte Ad-hoc-Google-Dokumente, Miro-Boards, Figjam-Boards usw. erstellt.

Mit den meisten Wissensdatenbank-Tools können Sie Dokumente aus Google Docs, Notion oder einer anderen gängigen Wissensdatenbank importieren, die Sie gerade verwenden. Sobald Sie sie importiert haben, organisieren Sie sie nach Kategorien und benennen Sie sie richtig. Wenn Ihre Wissensdatenbank-Software über eine Funktion zum Überprüfen des Status wie Slite verfügt, verwenden Sie sie, um Dinge wie technische Spezifikationen, Entwicklerrichtlinien usw. zu überprüfen.

Schritt 3: Beginnen Sie mit dem Schreiben der Dokumente, die noch nicht existieren, aber existieren sollten.

In Schritt drei ist es an der Zeit, mit dem eigentlichen Inhaltserstellungsprozess zu beginnen. Wissensschaffung ist niemals ein Job für eine einzelne Person. Es ist ein kollaborativer Prozess, und deshalb sollten Sie Ihr Team in dieser Phase einbeziehen.

Dies hat 2 Vorteile:

1. Es geht schneller, wenn alle dazu beitragen, indem sie sich an ihre Zeitpläne halten.
2. Es kurbelt die Dokumentationskultur in Ihrem Team an

Die beste technische Dokumentation entsteht in der Regel, wenn:

1. Jedes Dokument einen Eigentümer und Mitwirkende hat
2. Autoren gründlich darüber informiert werden, worüber sie schreiben sollen
3. Autoren einfache Sprache, Überschriften und viele Bilder verwenden, um ihre Dokumentation äußerst lesbar zu machen.
4. Autoren wissen, wer das Dokument alles lesen wird
5. Jedes fertiggestellte Dokument wird mindestens einmal von einer anderen Person überprüft.
6. Die meisten Dokumente erhalten einen Verifizierungsstatus, damit Ihr Team weiß, welche Dokumentation relevant ist und wann sie aktualisiert werden muss.

Dies stellt sicher, dass der Inhalt nicht nur klar, gut geschrieben und grammatikalisch korrekt ist, sondern auch für die Benutzer effektiv ist.

Wenn Ihre technische Dokumentation Anleitungen oder zu befolgende Schritte enthält, stellen Sie sicher, dass Ihre Teammitglieder diese Schritte tatsächlich testen und bestätigen, dass sie das erreichen, was sie sollen.

Schritt 4: Überprüfen Sie die Lesbarkeit Ihrer Dokumente

Da Entwickler, PMs und andere technische Mitarbeiter Ihre technische Dokumentation schreiben, ist es wichtig, sie auf Einfachheit zu überprüfen. Wenn Ihre Dokumentation von anderen Stakeholdern nicht verstanden werden kann, ist sie wertlos.

Stellen Sie daher sicher, dass Ihre Dokumentation:

• Bilder, Videos usw. enthält, um komplexe SOPs/Anleitungen aufzuschlüsseln (falls vorhanden)
• Interne Links zu verwandten/relevanten Artikeln enthält
• In mehrere Unterüberschriften unterteilt ist
• Extrem einfache Sprache verwendet
• Überfliegbar ist (Menschen ziehen es vor, Inhalte zu überfliegen, anstatt Absätze Wort für Wort zu lesen)

Es ist wichtig, sie einer Testphase zu unterziehen und auf organisatorische Probleme, verwirrende Informationen und Usability-Probleme zu prüfen.

Um diesen Schritt zu erreichen, können Sie auch externe Benutzer suchen, die Ihre Dokumentation testen. Lassen Sie sie sie durchlesen, verwenden Sie sie, um ihnen bei der Erledigung der Aufgaben zu helfen, für die sie gedacht ist, und geben Sie Ihnen ihr ehrliches Feedback. Es ist wichtig sicherzustellen, dass Ihre Tester extern sind, da sie Ihre Dokumentation mit frischen Augen betrachten und keine Vorurteile haben, die ihre Bewertung beeinflussen.

Schritt 5: Veröffentlichen, Feedback sammeln, iterieren.

Sie kennen diese Produktphilosophie. Sie müssen sie nur auch auf Ihre Dokumentation anwenden.

Sobald Sie Ihre technische Dokumentation veröffentlicht haben, bewerben Sie sie und bitten Sie die Benutzer proaktiv um Feedback.

Zweitens legen Sie Wartungs- und Hygieneprotokolle für Ihre Dokumentation fest. Technische Dokumente sind dynamisch und werden in Übereinstimmung mit den Produkten, die sie abdecken, aktualisiert und geändert. Daher ist es eine gute Idee, ein Protokoll zu erstellen, das detailliert beschreibt, was zu tun ist, wenn neue Informationen hinzugefügt, Änderungen integriert oder allgemeine Wartungsarbeiten durchgeführt werden müssen.

Viele Unternehmen entscheiden sich für die Implementierung eines Wartungsplans für ihre Dokumentation. Sie legen bestimmte Termine fest, an denen sie bewerten, ob Änderungen vorgenommen werden müssen, damit alle ihre Informationen immer auf dem neuesten Stand sind und Änderungen nie übersehen werden.

Beispiele/Inspiration für die beste technische Dokumentation

Hier sind 7 gute Beispiele für Entwicklerdokumentation, die von internen und externen Stakeholdern gleichermaßen geliebt wird:

Beispiel 1: Stripe - Der Maßstab für API-Dokumentation

Was gut ist

• Sticky Sidebar zur Navigation: Die Dokumentation von Stripe verfügt über eine Sticky Sidebar/ein Inhaltsverzeichnis, das die Benutzernavigation erheblich verbessert, indem es einfachen Zugriff auf verschiedene Abschnitte ohne Scrollen ermöglicht. Die Seitenleiste strukturiert die gesamteDokumentation wie ein Lehrbuch. So können Sie einfach über die Navigationsleiste von einem Dokument zum anderen springen.
• Sticky Interactive Sandbox: Der Vorschau-/Live-Sandbox-Codeabschnitt ermöglicht es Entwicklern, Code in Echtzeit zu schreiben, zu testen und anzuzeigen, was ihn zu einem unschätzbaren Werkzeug für das Lernen und Experimentieren macht.
• Code-Kopierfunktion: Diese Funktionalität ermöglicht es Benutzern, Code-Snippets einfach zu kopieren und in ihren Projekten zu verwenden, wodurch der Entwicklungsprozess optimiert wird.

Was schlecht ist

• Nichts wirklich. Die Dokumentation von Stripe macht alles richtig. Sie ist einfach zu lesen, der Code ist für Entwickler leicht zu kopieren und die Benutzeroberfläche ist sehr intuitiv.

Die klare, prägnante und interaktive Natur der Dokumentation von Stripe hat sie zum bevorzugten Favoriten unter Entwicklern gemacht, insbesondere im Vergleich zur Software-Dokumentation von PayPal.

Beispiel 2: MDN Web Docs - Ein äußerst knapper Zweitplatzierter

Was gut ist

• KI-Hilfe: Es ist das einzige Beispiel für technische Dokumentation in dieser Liste, das KI für die Suche in technischer Dokumentation hinzugefügt hat. Es bietet MDN-bezogene Antworten mit konsultierten Links, wodurch die Informationsbeschaffung effizient und effektiv wird.
• Umfassender Inhalt: Bietet eine umfassende Palette von Themen und ist damit umfassender als viele seiner Konkurrenten. Es verfügt über Dokumente, die von internen Teams, Fachexperten, technischen Redakteuren usw. erstellt wurden.
• Dedizierter Playground: Ermöglicht es Benutzern, direkt in der Dokumentation mit Code zu experimentieren, wodurch das Lernerlebnis verbessert wird.

Was schlecht ist

• Trotz seiner umfassenden Abdeckung fehlt MDN eine einzige Master-URL, um einfach zwischen verschiedenen Abschnitten zu springen, was einige Benutzer als unpraktisch empfinden.

Es ist jedoch erwähnenswert, dass die KI-Hilfefunktion den Mangel an Master-Navigation mehr als ausgleicht.

Beispiel 3: Twilio - Am nächsten an Stripe und am besten in der Prozessdokumentation

Was gut ist

• Interaktive Sandbox: Wie Stripe bietet Twilio eine Sandbox für Live-Code-Vorschauen, die das praktische Lernen verbessert.
• Seitenbewertungsoption: Benutzer können Dokumentationsseiten bewerten und so direktes Feedback zur Verbesserung der Ressourcen geben.

Was schlecht ist

• Navigationsherausforderungen: Einige Benutzer finden es langsamer, durch die Dokumentation zu navigieren, möglicherweise aufgrund ihrer umfassenden Natur.

Die Dokumentation von Twilio ist äußerst detailliert und in Bezug auf die Benutzererfahrung am ehesten mit Stripe vergleichbar. Einige Entwickler finden das Layout von Stripe jedoch sauberer und einfacher zu navigieren.

Beispiel 4: Django - Erledigt die Arbeit

Was gut ist

• Umfassende Abdeckung: Die Dokumentation von Django deckt alles ab, von den Grundlagen für Anfänger bis hin zu fortgeschrittenen Themen für erfahrene Entwickler, was sie zu einer zentralen Anlaufstelle für Django-Benutzer macht.
• Gut organisiert: Die Dokumentation ist logisch organisiert, sodass Entwickler die spezifischen Informationen, die sie benötigen, leicht finden können.

Was schlecht ist

• Aufgrund ihrer Umfassendheit könnte es für neue Benutzer schwierig sein, sich in der riesigen Menge an verfügbaren Informationen zurechtzufinden.

Wichtiger Hinweis

• Die Dokumentation von Django ist ein Goldstandard für Framework-Dokumentation und bietet detaillierte Anleitungen und Tutorials, die sowohl für Anfänger als auch für erfahrene Entwickler von entscheidender Bedeutung sind.

Beispiel 5: Laravel - Minimalistisch, aber umfassend

Was gut ist

• Minimalistische Navigation: Eine minimalistische Sticky Sidebar vereinfacht die Navigation und erleichtert es Benutzern, das zu finden, was sie benötigen, ohne Ablenkung.
• Dark Mode Toggle: Die Option, zwischen hellem und dunklem Modus zu wechseln, berücksichtigt unterschiedliche Benutzerpräferenzen und verbessert die Lesbarkeit.

Was schlecht ist

• Während ihre Einfachheit eine Stärke ist, könnten einige Benutzer interaktivere Elemente suchen, ähnlich denen in der Dokumentation von Stripe oder Twilio.

Die Dokumentation von Laravel zeichnet sich vor allem durch ihre Einfachheit und Effektivität aus, insbesondere durch die Art und Weise, wie sie Tabellen, Bilder und einfache Sprache verwendet, um komplexe Themen zu vermitteln.

Beispiel 6: DigitalOcean - Definiert die Bedeutung von umfassend neu

Was gut ist

• Community-Engagement: Funktionen wie ein Kommentarbereich am Ende von Tutorials fördern ein starkes Gemeinschaftsgefühl.
• One-Click-Copy-Buttons: Verbessert die Benutzerfreundlichkeit, indem es Benutzern ermöglicht, Code-Snippets einfach zu kopieren.
• Sie haben einen Artikel für alles: Sie haben alle ihre Grundlagen bis hin zu den kleinsten Anwendungsfällen abgedeckt.

Was schlecht ist

• Obwohl umfassend, setzen einige Tutorials möglicherweise ein gewisses Maß an Vorwissen voraus, was sie für absolute Anfänger möglicherweise weniger zugänglich macht.

Die Dokumentation von DigitalOcean zeichnet sich durch die Einbindung der Community aus und bietet eine Plattform nicht nur zum Lernen, sondern auch zur Diskussion und zum Wissensaustausch.

Beispiel 7: Arch Wiki - Ein vertrautes Layout

Was gut ist

• Einfachheit: Bietet eine Wikipedia-ähnliche Einfachheit in ihrem Design und konzentriert sich darauf, Informationen auf die einfachste Art und Weise bereitzustellen.
• Interlinking: Ausgezeichnete Querverbindungen zwischen Seiten erleichtern die Navigation und bieten ein umfassendes Informationsnetz.

Was schlecht ist

• Der minimalistische Ansatz ist möglicherweise nicht für Benutzer geeignet, die eine stärker geführte, tutorialbasierte Dokumentation mit interaktiven Elementen bevorzugen.

Das Arch Wiki ist bekannt für seine Genauigkeit, aktuelle Informationen und seine schnörkellose Struktur, was es zu einem Favoriten unter Benutzern macht, die Präzision und Tiefe in der Dokumentation bevorzugen.

Do's and Don'ts einer guten Dokumentation

Was zu tun ist

1. Machen Sie es einfach zu navigieren: Verwenden Sie eine Seitenleiste oder eine übersichtliche Inhaltsseite, damit die Leute schnell finden, was sie brauchen, genau wie Stripe.
2. Fügen Sie interaktive Beispiele hinzu: Lassen Sie Benutzer Code ausprobieren oder ihn in Aktion sehen. Stripe und Twilio sind darin großartig und machen das Lernen unterhaltsamer und praktischer.
3. Halten Sie es einfach und klar: Schreiben Sie auf eine Weise, die leicht zu verstehen ist. Laravel ist darin gut und verwandelt komplexe Ideen in einfache Erklärungen. Technisches Schreiben sollte für jeden zugänglich sein.
4. Lassen Sie Benutzer miteinander sprechen: Haben Sie einen Ort für Feedback oder Diskussionen. Die Tutorials von DigitalOcean sind hilfreicher, weil sie Benutzerkommentare und Diskussionen enthalten.
5. Decken Sie relevante Informationen ab: Sprechen Sie sowohl einfache als auch komplexe Themen an, um sowohl neuen als auch erfahrenen Benutzern zu helfen. MDN Web Docs macht dies gut, indem es viele detaillierte Anleitungen zu Webtechnologien anbietet.
6. Oft aktualisieren: Halten Sie Ihre Dokumentation immer auf dem neuesten Stand, um sicherzustellen, dass die Benutzer die neuesten Informationen haben. Das Arch Wiki ist immer auf dem neuesten Stand, was super hilfreich ist.

Was zu vermeiden ist

1. Überlasten Sie Benutzer nicht: Zu viele Informationen auf einmal können überwältigend sein. Es ist besser, Inhalte so zu organisieren, dass sie leicht zu verdauen sind.
2. Überspringen Sie keine Beispiele: Benutzer benötigen Beispiele, um zu verstehen, wie die Dinge funktionieren. Stellen Sie sicher, dass Ihre Dokumentation praktische, reale Beispiele enthält. Gehen Sie die Extrameile und fügen Sie Dinge wie Screenshots oder Bildschirmaufzeichnungen zu Ihren technischen Inhalten hinzu.
3. Ignorieren Sie nicht das Design: Eine unordentliche oder schwer lesbare Dokumentationsseite kann Benutzer abschrecken. Stellen Sie sicher, dass Ihre Seite ordentlich und einfach zu bedienen ist.
4. Ignorieren Sie kein Feedback: Benutzervorschläge können helfen, Ihre Dokumentation zu verbessern. Achten Sie darauf, was Benutzer sagen.
5. Nehmen Sie nicht an, dass jeder alles weiß: Denken Sie daran, dass nicht jeder ein Experte sein wird. Fügen Sie grundlegende Anleitungen für Anfänger und detailliertere Informationen für diejenigen hinzu, die sie benötigen.
6. Vergessen Sie nicht die Suche: Eine gute Suchfunktion erleichtert es Benutzern, genau das zu finden, was sie benötigen, ohne Zeit zu verschwenden.
7. Bombardieren Sie keine Akronyme: Achten Sie auf die Verwendung von Akronymen. Während sie den Schreibprozess beschleunigen, stellen Sie sicher, dass Sie die vollständige Form von Akronymen für diejenigen angeben, die sie möglicherweise nicht kennen.

Abschließende Erkenntnis - Strukturieren Sie wie ein Lehrbuch, haben Sie ein funktionales Design und verbessern Sie es ständig.

Denken Sie daran, die beste Dokumentation wächst und passt sich ihren Benutzern an. Sie hört auf ihre Kämpfe und Triumphe und entwickelt sich weiter, um ihre Bedürfnisse besser zu erfüllen. Es geht nicht nur darum, alle Antworten zu haben, sondern darum, diese Antworten für jeden zugänglich und ansprechend zu machen, vom neugierigen Anfänger bis zum erfahrenen Experten.

Nehmen Sie sich also ein Beispiel an den Playbooks von Stripe, MDN, Laravel und anderen, die mit gutem Beispiel vorangehen. Versuchen Sie, eine Dokumentation zu erstellen, die nicht nur informiert, sondern Ihre Benutzer inspiriert und befähigt.

Einfach ausgedrückt,

Gute technische Dokumentation ist ein Verkaufsargument Ihres Produkts.

Großartige technische Dokumentation bedeutet, dass jeder schneller liefert. Deshalb setzen sich Entwickler intern dafür ein, Apps für großartige Dokumentation zu verwenden. Seien Sie einer von ihnen.