Wie man eine gute Dokumentation schreibt (eine schrittweise Anleitung)

Ihr Leben kann so viel einfacher sein, wenn Sie wissen, wie man Dokumentationen schreibt - gute, hilfreiche Dokumentationen, die ihren Benutzern tatsächlich das geben, was sie brauchen.

Schließlich liest ja jeder die Dokumentation:

• Marketingteams arbeiten mit Playbooks - einer Art Marketingdokumentation. 
• Support- und Technikteams verwenden Benutzerhandbücher, Installationshandbücher, Code-Notizen - die "zentrale" technische Dokumentation.
• Andere stützen sich auf Standardarbeitsanweisungen, Referenzmaterial, Prozessdokumente, Checklisten - typische Wissensdokumente eines Unternehmens.

Auch die Kunden nutzen die kundenorientierte Dokumentation, um sich mit einer Lösung vertraut zu machen oder ihre Probleme selbst zu beheben (Tier 0 Support).

Es gibt zwar keine Standardmethode für die Erstellung all dieser Unterlagen, aber die grundlegenden Schritte sind immer gleich. Doch bevor wir uns diese ansehen, sollten wir einen kurzen Blick auf die verschiedenen Dokumentationsarten werfen. Je nach Zweck kann eine Dokumentation einer von vier Arten angehören.

Arten von Dokumentation

In seinem Vortrag über die Arten der Dokumentation unterteilt Daniele Procida von der Divio AG die Dokumentation in vier Typen:

• Lernorientierte Tutorien
• zielgerichtete Anleitungen
• verständnisorientierte Gespräche
• informationsorientiertes Nachschlagewerk

Wie Sie aus seinen Ausführungen ersehen können, hat jede Dokumentation ein anderes Ziel, und die für die Dokumentation Verantwortlichen müssen dieses Ziel jedes Mal festlegen, wenn sie sich an die Erstellung einer Dokumentation machen.

In diesem Sinne beginnen wir mit unserem Leitfaden für das Verfassen von Dokumentationen.

Bestimmen Sie, ob Sie es wirklich dokumentieren müssen

Ihr Produkt kann vielleicht hundert Dinge tun. Vielleicht gibt es sogar noch mehr Möglichkeiten, es anzupassen. Sie könnten eine Codebasis von Tausenden von Zeilen haben. Und vielleicht generieren Sie bei Ihrer täglichen Arbeit auch eine Menge an Wissen. 

Aber es ist nicht möglich, alles zu dokumentieren... und nicht alles muss dokumentiert werden. 

Bevor Sie also die Frage "Wie schreibe ich eine Dokumentation" beantworten, sollten Sie wissen, ob Sie überhaupt dokumentieren müssen.

Bevor Sie eine Dokumentation erstellen, sollten Sie sich Gedanken über Ihre Zielleser machen. Die Zielleser Ihrer Dokumentation können alle sein, vom Endbenutzer bis hin zu Ihren Softwareentwicklern oder Personalverantwortlichen. Sind es Wissensarbeiter? Überlegen Sie, womit diese Zielgruppen zu kämpfen haben... und ob Sie sie durch eine Dokumentation wirklich in die Lage versetzen können, besser zu arbeiten.

Überlegen Sie auch, wie sie die Dokumentation verwenden werden. Denken Sie daran, wie die vorgesehenen Benutzer mit Ihrer Dokumentation umgehen werden.

Werden Ihre Kunden Ihrer Dokumentation Schritt für Schritt folgen, um mit Ihrer Lösung zu arbeiten? Das macht Ihre Dokumentation "zielorientiert".

Oder werden Ihre Entwickler sie bei der Arbeit an Ihrem nächsten Release-Zyklus verwenden und zusammenarbeiten? In diesem Fall handelt es sich um eine "verständnisorientierte" Dokumentation.

Oder wird Ihre Personalabteilung bei der Bearbeitung von Bewerbungen darauf zurückgreifen? Sie haben hier eine "informationsorientierte" Dokumentation.

Und wird Ihre Dokumentation ihnen wirklich helfen?

Abgesehen davon sollten Sie auch darüber nachdenken, wie Ihre Dokumentationsbemühungen Ihnen auf einer höheren Ebene helfen werden:

• Verbessert Ihre Dokumentation den Tier-Null-Support und ermöglicht es Ihren Endbenutzern, ihre Probleme selbst zu lösen (Ablenkung)? 
• Würden Ihre Teams dadurch in ihrer Arbeit besser werden?
• Wird Ihr Team produktiver werden? 

Finden Sie heraus, wann Sie es dokumentieren müssen

Generell gilt, dass man nicht zu früh (oder zu spät) anfangen sollte.

Wenn Sie sich nicht sicher sind, wie ein Prozess tatsächlich ablaufen wird oder wie Sie Ihre "Vision" umsetzen wollen, ist es am besten, ihn nicht zu dokumentieren und zu warten, bis sich die Dinge ein wenig konkretisieren.

Wenn Sie z. B. im nächsten Quartal eine umfangreiche Aktualisierung planen und sich die Arbeit erst in der Konzeptionsphase befindet, sollten Sie die Dokumentationsressourcen noch nicht einsetzen. 

Dies ist der "agile" Ansatz für die Dokumentation.

Bestimmte Dokumentationsarten (z. B. Verfahren und Prozesse) sollten am besten dann erstellt werden, wenn sie tatsächlich ausgeführt werden. 

Konzentrieren Sie sich auf den besten Weg zur Dokumentation

Je nachdem, welche Arten von Unterlagen Sie benötigen, brauchen Sie einen oder mehrere Orte, an denen Sie alles aufbewahren können. Diese dienen Ihnen als einzige Quelle der Wahrheit. 

Chastity Blackwell von Yelp berichtet von den Frustrationen, die entstehen, wenn die gesamte Dokumentation nicht an einem Ort gespeichert ist:

Sie haben ein Dokument, in dem alles über diesen Dienst erklärt wird, und Sie sind sicher, dass die Informationen, die Sie zur Lösung dieses Problems benötigen, dort zu finden sind - irgendwo. "Sie können versuchen, im Wiki danach zu suchen, oder vielleicht ist es in der Google Docs Repo. Oh, und ich habe ein paar Notizen in meinem Home-Verzeichnis, und ich glaube, ich habe vor einer Weile eine E-Mail darüber gesehen."

Natürlich wollen Sie nicht, dass Ihnen das passiert. Deshalb müssen Sie Ihr(e) Dokumentationswerkzeug(e) mit Bedacht auswählen. Wenn Sie für Endbenutzer dokumentieren, ist es am besten, eine einfach zu befüllende Wissensdatenbanklösung wie Heroic Knowledge Base zu verwenden.

Wenn Sie für Ihre Teams dokumentieren, sollten Sie sich für eine Wiki-Lösung wie WikiPress oder eine interne Wissensmanagement-Lösung wie Heroic Knowledge Base entscheiden (ja, das ist auch eine Lösung!). Oder schauen Sie sich einige dieser Optionen für Wissensmanagement-Lösungen an.

Wenn Sie schließlich Code dokumentieren, sollten Sie einige der spezielleren technischen Dokumentationslösungen und Dokumentenmanagementsysteme in Betracht ziehen. Einige Allzweck-Wissensdatenbanklösungen wie Heroic Knowledge Base funktionieren ebenso gut als technische Dokumentationslösungen.

Achten Sie bei der Auswahl Ihres Dokumentationssystems darauf, dass es leicht zu aktualisieren ist, denn Sie werden Ihre Dokumentation möglicherweise häufig aktualisieren müssen! Ihr Dokumentationswerkzeug sollte auch eine ausgezeichnete Suchfunktion bieten. 

Entscheiden Sie, was Sie schreiben wollen 

Da die Dokumentation so viele verschiedene Formen annehmen kann, ist es wichtig, ein Format festzulegen, bevor man sie schreibt. 

Bei HeroThemes beispielsweise verwenden wir für unsere kundenorientierte Dokumentation eine Mischung aus FAQs, Installationsanleitungen, Anleitungen zur Fehlerbehebung, Listen mit Tipps und Tricks und anderen Elementen. Auch die meisten unserer Kunden verwenden eine ähnliche Zusammensetzung. 

Je nachdem, welche Dokumentation Sie erstellen und für wen, müssen Sie wissen, welche Formen Ihre Dokumentation annehmen kann. Jacob Kaplan-Moss spricht in What to write ausführlich über diese Formen. Er erklärt, dass Tutorials, thematische Leitfäden und Referenzmaterial in den meisten Fällen den Großteil der Dokumentation ausmachen: 

• Tutorials: Tutorials oder Anleitungen sind die einfachste Form der Dokumentation. Für unsere kundenorientierte Dokumentation sind Tutorials unsere How-to-Ressourcen, die unsere Nutzer verwenden, um ihrer Website mit unserem Plugin eine Wissensdatenbank hinzuzufügen oder sie mit Artikeln zu füllen. 
• Thematische Leitfäden: Thematische Leitfäden gehen in der Regel viel tiefer als Tutorials und befassen sich mit spezielleren Themen. Für uns sind das unsere Leitfäden zu Themen wie Übersetzung und Integration. Wir kategorisieren sie grob als fortgeschrittene Themen.
• Referenz: Im Zusammenhang mit unserer kundenorientierten Dokumentation enthält dieser Typ Informationen über unsere Integrationen mit unseren Partnern, die unsere Benutzer bei der Einrichtung ihrer Integrationen hilfreich finden könnten. Oder Links zu Informationen, die bei der Implementierung einer unserer HeroThemes Lösungen nützlich sein könnten.

Beginnen Sie mit einer README-Datei (und bauen Sie darauf auf)

Nachdem das alles geklärt ist, können Sie jetzt mit dem Schreiben beginnen. Der eigentliche Schreibteil der Dokumentation beginnt mit einer README-Datei. Betrachten Sie sie als Deckblatt oder Gliederung für Ihre Dokumentation. 

Wenn Sie an Ihrer Software-Dokumentation arbeiten, die Ihre (Entwickler-/Tester-/Optimierer-)Kollegen verwenden werden, wird Ihre README-Datei auf eine bestimmte Weise aussehen. 

Und wenn Sie eine Dokumentation für den Kunden schreiben, sollten Sie sie so anpassen, dass sie für die vorgesehene Zielgruppe und die zu erledigende Arbeit sinnvoll ist. Der Inhalt bleibt jedoch mehr oder weniger derselbe. Unten sehen Sie, wie ein Support-Artikel, der erklärt, wie eine Integration funktioniert, mit einem eigenen Deckblatt beginnt.

Nehmen Sie nun einfach Ihre READMe-Datei oder die Gliederung Ihrer Dokumentation und füllen Sie sie Abschnitt für Abschnitt aus. Hier sind ein paar Ressourcen aus unserem Blog, die Ihnen beim Ausfüllen Ihrer Dokumentation helfen:

• Die ultimative Vorlage für Wissensdatenbankartikel (Infografik): Wir haben die erfolgreichsten Wissensdatenbankartikel unserer Kunden untersucht und entschlüsselt, wie ein guter Wissensdatenbankartikel aussieht. Solche Artikel machen einen wesentlichen Teil Ihrer nutzerorientierten Dokumentation aus. Nutzen Sie also diese Infografik, um sie in Rekordzeit zu erstellen.
• Wie man gründliche Schritt-für-Schritt-Standardarbeitsanweisungen (SOPs) schreibt: Dies ist eine kurze Anleitung zum Schreiben von Anleitungen oder Standardarbeitsanweisungen, die Schritt-für-Schritt-Anweisungen zur Ausführung der beabsichtigten Arbeit enthalten - sehr nützlich bei der Erstellung eines internen Unternehmens-Wikis oder einer Wissensdatenbank.
• Was ist Prozessdokumentation? Und wie Sie Ihre Prozesse richtig dokumentieren: Eine weitere Kurzanleitung zum Verfassen von Prozessdokumentation, einem wesentlichen Bestandteil Ihrer unternehmensinternen Wissensdokumentation. 
• Wie man häufig gestellte Fragen schreibt & 5 einfache Wege, um die perfekten Antworten auf Ihre FAQs zu schreiben: Diese beiden Beiträge helfen Ihnen, Ihre FAQs innerhalb einer Stunde zu verfassen und eine Menge von Anfragen vor dem Verkauf abzuwehren.

Vergessen Sie nicht, einen Überprüfungs- und Testteil hinzuzufügen.

Die Überprüfung ist ein wesentlicher Bestandteil des Dokumentationsprozesses. Es hilft Ihnen sicherzustellen, dass Ihre Dokumentation tatsächlich funktioniert.

In seinem fünfstufigen Prozess zur Überprüfung von Dokumentationen sagt der technische Redakteur Tom Johnson, dass die erste Stufe unumgänglich ist, in der Sie - der Redakteur der Dokumentation - das Produkt für sich selbst zum Laufen bringen, indem Sie den von Ihnen geschriebenen Schritten folgen.

Einen Zeitplan für die Aktualisierung festlegen

Die Dokumentation beginnt zu veralten, sobald sie veröffentlicht ist. Sie brauchen also einen Aktualisierungsplan.

Die Häufigkeit der Aktualisierungen hängt von der Dokumentation ab, die Sie betrachten. Ihre benutzerseitige Dokumentation muss zum Beispiel nur dann aktualisiert werden, wenn Sie Ihr Produkt aktualisieren.

Die Dokumentation für die Entwickler - die Dokumentation des technischen Codes - wird ständig fortgeführt (Inline-Dokumentation).

Ihre interne Wissens-/Arbeitsdokumentation hingegen könnte jedes Mal aktualisiert werden, wenn sich etwas ändert - zum Beispiel, wenn Sie Ihr aktuelles Projektmanagement-Tool ersetzen oder wenn Sie einfach nur eine optimierte Art und Weise entdecken, eine bestimmte Arbeit zu erledigen. Die Erfassung von Stammeswissen und die Erfassung von allgemeinem Wissen sind einige der laufenden Übungen für eine solche Dokumentation.

Wenn es sinnvoll ist, sollten Sie in Ihrer Dokumentation ein Änderungsprotokoll führen, damit sich die Benutzer nicht verloren fühlen, wenn sie eine aktualisierte Version sehen.

Im Rahmen der Aktualisierung Ihrer Dokumentation sollten Sie auch veraltete und doppelte Dateien beseitigen. Eine Suche in Ihrer Dokumentation sollte niemals mehrere Versionen desselben Support-Inhalts ergeben. Für jedes Thema sollte es nur eine Ressource geben. 

Das war's...

Sobald Sie diesen allgemeinen Leitfaden für das Verfassen von Dokumentationen an Ihre Arbeitsabläufe angepasst haben, dokumentieren Sie Ihren Prozess für das Verfassen von Dokumentationen

Auf diese Weise können Sie nicht nur Ihre Dokumentation standardisieren, sondern auch andere in die Lage versetzen, darauf aufzubauen, denn Dokumentation ist immer ein Prozess.

Nun zu Ihnen... Wie gehen Sie derzeit bei der Erstellung von Dokumentationen vor?