Wie man technische Dokumentation im Jahr 2025 erstellt - Eine einfache Anleitung

Was ist technische Dokumentation?

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

Technische Dokumentation ist ein weit gefasster Begriff. Er umfasst alles von Ihrem ersten PRD bis zu Ihren API-Dokumenten für andere Entwickler. Lassen Sie uns ihn etwas genauer definieren.

Verschiedene Arten technischer Dokumentation – was dazugehört 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 zeigen, wie man etwas benutzt, wie eine Kamera oder Software. Sie sind voll von Schritt-für-Schritt-Anweisungen.

• Wer es benutzt: Jeder, der versucht herauszufinden, wie man ein Produkt benutzt
• Wann es erstellt wird: Nachdem das Produkt hergestellt, aber bevor es verkauft wurde

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 es benutzt: Programmierer und App-Entwickler
• Wann es erstellt wird: Während das Tool für Programmierer erstellt wird oder direkt nach dessen Fertigstellung

3. Handbücher für Systemadministratoren

Dies ist ein Handbuch für Technikprofis, die Computersysteme einrichten, reparieren und sicherstellen, dass sie reibungslos funktionieren.

• Wer es benutzt: Technischer Support und IT-Mitarbeiter
• Wann es erstellt wird: Nachdem das Computersystem einsatzbereit ist

4. Installationsanleitungen

Diese Anleitungen zeigen Ihnen die Schritte, um eine Software oder Hardware in Betrieb zu nehmen.

• Wer es benutzt: Jeder, der neue Technik einrichtet, vom alltäglichen Benutzer bis zum IT-Personal
• Wann es erstellt wird: Nach der Herstellung des Produkts, aber bevor es auf den Markt kommt

5. Fehlerbehebungsanleitungen

Haben Sie ein Problem mit Ihrer Technik? Diese Anleitungen helfen herauszufinden, was falsch ist und wie man es behebt.

• Wer es benutzt: Benutzer mit Problemen, Helpdesks, IT-Profis
• Wann es erstellt wird: Nachdem das Produkt auf dem Markt ist, mit Updates, wenn neue Probleme auftreten

6. Whitepapers

Betrachten Sie diese als tiefgehende Einblicke in ein spezifisches technisches Thema, die Lösungen für technische Herausforderungen bieten oder erklären, wie ein Produkt helfen kann.

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

7. Release Notes

Wenn Software ein Update erhält, informieren Release Notes darüber, was neu ist, was verbessert wurde und welche Probleme noch bestehen.

• Wer es benutzt: Jeder, der die Software benutzt
• Wann es erstellt wird: Zusammen mit Software-Updates

8. Produktdokumentation

Sie werden viel schreiben müssen, um Ihre Produktentwicklung zu optimieren. Und all Ihre Projektpläne sind Teil der technischen Dokumentation. Diese detaillierte Liste sagt Ihnen genau, was ein Produkt kann und welche Funktionen es hat.

• Wer es benutzt: Produktmanager und andere Teammitglieder setzen sich in der Regel dafür ein.
• Wann es erstellt wird: Zu Beginn der Produktentwicklung

9. FAQs (Häufig gestellte Fragen)

Hier finden Sie Antworten auf häufig gestellte Fragen zur Nutzung eines Produkts oder einer Dienstleistung.

• Wer es benutzt: Kundensupport-Teams und Benutzer, die schnelle Antworten suchen
• Wann es erstellt wird: Beginnt mit den häufigsten Fragen in Demo-/Discovery-Anrufen. Es wird erweitert, indem die wahrscheinlichsten Fragen hinzugefügt werden, die andere Leute stellen werden. FAQs sind sehr volatil, basierend auf Ihrem ICP, ihren Meilensteinen der Reise usw.

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

10. Entwicklerhandbücher

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

• Wer es benutzt: Programmierer und Softwareentwickler
• Wann es erstellt wird: Während der Entwicklung der Technologie und wird bei Änderungen aktualisiert

Wer nutzt 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 Leute einige Dokumente mit technischen Anleitungen, obwohl sie es nicht sind. Während einiges davon – wie Ihr HR-Handbuch – offensichtlich nicht-technische Dokumentation ist, fallen einige Dokumente in eine Grauzone. Hier ist ein kurzer Überblick:

• Marketingmaterialien: Dinge wie Broschüren und Websites, die vielleicht Fachjargon verwenden, aber eigentlich versuchen, Sie zum Kauf zu bewegen. Sie sind nicht dazu da, Ihnen beizubringen, wie man das Produkt benutzt oder repariert.
• Geschäftspläne und Berichte: Diese Dokumente behandeln die technische Seite eines Geschäfts oder neue Produktideen, aber es geht hauptsächlich um die Erstellung von Plänen, die Schätzung zukünftiger Einnahmen und die Marktanalyse.
• Interne Richtlinien und Verfahren: Wichtig für die Führung eines Unternehmens, aber sie betreffen eher Regeln, die richtige Vorgehensweise und das, was Mitarbeiter tun sollten, nicht die Nutzung von Technik.
• Technische Vorschläge: Sie schlagen neue Technologieprojekte oder -lösungen vor, sprechen über die Vorteile, die sich daraus ergeben können, ob es möglich ist und wie viel es kosten könnte, anstatt Schritt-für-Schritt-Anleitungen zu geben.
• User Stories und Anwendungsfälle: Werden häufig bei der Softwareentwicklung verwendet, um zu erklären, was eine Funktion aus Sicht des Benutzers tun soll. Sie helfen herauszufinden, was Benutzer benötigen, sind aber keine detaillierten technischen Anweisungen. Verstehen Sie uns nicht falsch, User Stories und Anwendungsfälle helfen Teams bei der Entscheidung, was als Nächstes entwickelt werden soll. Aber es zählt immer noch als Marktforschung, nicht als technische Dokumentation.

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

‍

Wie man technische Dokumentation erstellt

Schritt 0: Erstellen Sie Ihren Leitfaden für den technischen Schreibstil

Ihr Leitfaden für den technischen Schreibstil hilft allen Mitwirkenden, einen konsistenten 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 zu pflegen.

Und das sollten Sie auch.

Auch wenn es jetzt vielleicht nicht wichtig erscheint, wird es in Monaten wichtig sein, wenn Ihr Team und Ihre Benutzerbasis wachsen. Dies umfasst die Definition von Schriftarten, Schritt-für-Schritt-Anleitungen zur Dokumentenerstellung und Workflow-Details.

Schritt 1: Finden Sie heraus, was Sie jetzt sofort

Sie benötigen nicht sofort alle 10 Arten von Dokumentation. Unterschiedliche Bedürfnisse entwickeln sich und treten im Laufe 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 der Erstellung der Dokumentation, während die Entwicklung voranschreitet.
• Entwicklerhandbücher: Beginnen Sie mit der Arbeit an Anleitungen, wenn Ihr Produkt auf Entwickler abzielt, und aktualisieren Sie diese, sobald Funktionen finalisiert sind.
• Technische Vorschläge: Verfeinern Sie diese Dokumente weiter, wenn Anpassungen aufgrund von Stakeholder-Feedback oder sich änderndem Projektumfang erforderlich sind.

3. Monat 7 bis 12: Vorbereitungsphase für den Start

• Handbücher für Systemadministratoren: Beginnen Sie mit der Erstellung, sobald die Systemarchitektur gefestigt ist.
• Installationsanleitungen: Entwerfen Sie diese Anleitungen, sobald der Installationsprozess definiert ist.
• Benutzerhandbücher und Fehlerbehebungsanleitungen: 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 basierend auf Beta-Tests oder erwarteten Benutzeranfragen zusammen.
• Release Notes: Bereiten Sie sich auf den ersten Start vor und detaillieren Sie Funktionen, Fehlerbehebungen und bekannte Probleme.

4. Monat 13 bis 24: Nach dem Start und Wachstumsphase

• Alle vorherigen Dokumentationen aktualisieren: Änderungen, Updates und Feedback aus der realen Nutzung widerspiegeln.
• Kontinuierliche Updates:
• Produktspezifikationen: Aktualisieren Sie diese, wenn neue Funktionen hinzugefügt werden oder wesentliche Produktänderungen auftreten.
• API-Dokumentation und Entwicklerhandbücher: Halten Sie diese Dokumente aktuell, um die Beteiligung der Entwickler und die Benutzerfreundlichkeit zu fördern.
• Handbücher für Systemadministratoren und Installationsanleitungen: Überarbeiten Sie diese basierend auf Software-Updates oder Änderungen der Systemanforderungen.
• Benutzerhandbücher und Fehlerbehebungsanleitungen: Aktualisieren Sie diese Dokumente regelmäßig, um neue Lösungen aufzunehmen und zusätzliche Benutzerfragen zu beantworten.
• FAQs: Fügen Sie kontinuierlich neue Fragen hinzu, wenn Benutzer mehr mit dem Produkt interagieren.
• Release Notes: Mit jeder neuen Version oder jedem Update stellen Sie detaillierte Release Notes bereit, um Benutzer über Änderungen zu informieren.

Wie Sie sehen, wenn Sie gerade erst mit der Entwicklung Ihres Produkts begonnen haben, haben Sie möglicherweise nur verschiedene Iterationen Ihres PRD. Wenn Sie jedoch bereits gestartet sind und sich in der Wachstumsphase befinden, haben Sie höchstwahrscheinlich bereits alle Arten von technischer Dokumentation erstellt, aber diese könnte verstreut sein.

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

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

Sobald Sie Ihre Basis strukturiert haben, erhalten Sie ein klares Bild über alle Dokumentationen, die Sie zu diesem Zeitpunkt haben sollten.

Da Sie möglicherweise bereits einen Teil davon besitzen, beginnen Sie mit dem Import aus anderen Quellen. Anstatt auf eine leere Seite zu starren, importieren Sie die 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 Docs, Miro-Boards, Figjam-Boards usw. erstellt.

Die meisten Wissensdatenbank-Tools ermöglichen den Import von Dokumenten aus Google Docs, Notion oder jeder anderen beliebten Wissensdatenbank, die Sie derzeit verwenden. Nach dem Import beginnen Sie, sie in Kategorien zu organisieren und richtig zu benennen. Wenn Ihre Wissensdatenbank-Software eine Verifizierungsstatusfunktion wie Slite hat, verwenden Sie diese, um Dinge wie technische Spezifikationen, Entwicklungsrichtlinien usw. zu überprüfen.

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

Mit Schritt drei ist es Zeit, mit dem eigentlichen Inhaltserstellungsprozess zu beginnen. Wissenserstellung ist niemals eine Ein-Personen-Aufgabe. Es ist ein kollaborativer Prozess, und deshalb sollten Sie Ihr Team in dieser Phase einbeziehen.

Dies hat 2 Vorteile:

1. Es wird schneller erledigt, wenn jeder durch Einhaltung seiner Zeitpläne beiträgt.
2. Es stößt die Dokumentationskultur in Ihrem Team an

Die beste technische Dokumentation wird in der Regel erstellt, wenn:

1. Jedes Dokument einen Eigentümer und Mitwirkende hat
2. Autoren gründlich darüber informiert sind, was zu schreiben ist
3. Autoren einfache Sprache, Überschriften und viele Bilder verwenden, um ihre Dokumentation äußerst lesbar zu machen.
4. Autoren wissen, wer alles das Dokument 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 sein wird.

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

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

Da Entwickler, PMs und andere technische Fachleute 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.

Deshalb stellen Sie sicher, dass Ihre Dokumentation:

• Bilder, Videos usw. enthält, um komplexe SOPs/Anleitungen (falls vorhanden) aufzuschlüsseln
• Interne Links zu verwandten/relevanten Artikeln enthält
• Durch mehrere Unterüberschriften gegliedert ist
• Extrem einfache Sprache verwendet
• Überfliegbar ist (Menschen ziehen es vor, Inhalte zu überfliegen, nicht 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 diese 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 könnten.

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 Benutzer proaktiv um Feedback.

Zweitens, legen Sie Wartungs- und Hygieneprotokolle für Ihre Dokumentation fest. Technische Dokumente sind dynamisch und unterliegen Aktualisierungen und Änderungen entsprechend den Produkten, die sie abdecken. 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, sodass alle ihre Informationen immer aktuell 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 werden:

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 gesamte Dokumentation 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. Stripes Dokumentation 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 von Stripes Dokumentation hat sie zur bevorzugten Integration unter Entwicklern gemacht, insbesondere im Vergleich zur Software-Dokumentation von PayPal.

Beispiel 2: MDN Web Docs - Ein extrem 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 für das einfache Springen zwischen verschiedenen Abschnitten, was einige Benutzer als unbequem empfinden.

Es ist jedoch erwähnenswert, dass die KI-Hilfefunktion das Fehlen einer Master-Navigation mehr als wettmacht.

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.

Twilios Dokumentation ist extrem detailliert und in Bezug auf die Benutzererfahrung am ehesten mit Stripe vergleichbar. Obwohl einige Entwickler Stripes Layout sauberer und einfacher zu navigieren finden.

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önnten neue Benutzer es schwierig finden, sich durch die große Menge an verfügbaren Informationen zu navigieren.

Wichtiger Hinweis

• Djangos Dokumentation ist ein Goldstandard für Framework-Dokumentationen und bietet detaillierte Anleitungen und Tutorials, die sowohl für Anfänger als auch für erfahrene Entwickler entscheidend 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

• Obwohl ihre Einfachheit eine Stärke ist, könnten einige Benutzer interaktivere Elemente suchen, ähnlich denen, die in Stripes oder Twilios Dokumentation zu finden sind.

Laravels Dokumentation zeichnet sich vor allem durch ihre Einfachheit und Effektivität aus, insbesondere in der 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 abgedeckt, bis hin zu den kleinsten Anwendungsfällen.

Was schlecht ist

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

DigitalOceans Dokumentation zeichnet sich durch die Einbindung der Community aus und bietet eine Plattform nicht nur zum Lernen, sondern auch für Diskussionen und 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 könnte Benutzer, die eine stärker geführte, tutorialbasierte Dokumentation mit interaktiven Elementen bevorzugen, nicht ansprechen.

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

Do's und Don'ts guter 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.

Letzte 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 Schwierigkeiten und Erfolge und entwickelt sich weiter, um ihren Bedürfnissen besser gerecht zu werden. Es geht nicht nur darum, alle Antworten zu haben, sondern 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. Ziel ist es, 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 befürworten Entwickler intern die Verwendung von Apps für großartige Dokumentation. Seien Sie einer von ihnen.