Welchen Dokumentationsstil sollten Produktmanager verwenden, um die richtige Botschaft zu vermitteln?

*Die Dokumentation ist eine der wichtigsten und am meisten unterschätzten Komponenten eines Open-Source-Projekts und sollte nicht auf die leichte Schulter genommen werden.

Im Allgemeinen wird den meisten Open-Source-Projekten keine angemessene Aufmerksamkeit zuteil, weil ihre Autoren nicht wirklich daran interessiert sind, nicht in der Lage sind oder nicht die Zeit haben, eine effektive Dokumentationsumgebung für ihre API- und Produktdokumentation zu schaffen.

Ihre Anwendung kann noch so gut sein, wenn die Dokumentation unzureichend ist, können die Verbraucher keinen Nutzen aus ihr ziehen.

Aber selbst wenn sie aus irgendeinem Grund keine andere Wahl haben, als die Anwendung zu nutzen, werden sie nicht in der Lage sein, dies erfolgreich oder in der Weise zu tun, wie Sie es sich wünschen.

Zu verstehen, wie man eine exzellente Dokumentation erstellt, erfordert ein erhebliches Maß an Arbeit, ebenso wie die regelmäßige Überprüfung anderer Dokumentationsprojekte. Aber nehmen Sie mich beim Wort - als jemand, der eine Fülle von Dokumentationen für Docsie erstellt hat - wenn Sie Code erstellen, der von jemand anderem als Ihnen selbst verwendet wird, und insbesondere, wenn diese Leute Ihre Kunden sind, sollte Ihr Produkt gut dokumentiert, formatiert und dynamisch präsentiert werden.

Was ist der Unterschied zwischen Tutorials, Anleitungen, Erklärungen und Referenzen?

Viele Menschen glauben fälschlicherweise, dass sich die vier Ausdrücke auf denselben Gegenstand beziehen. Sie drücken jedoch eine Vielzahl von unterschiedlichen Bedeutungen aus. Diese verschiedenen Arten von Dokumentationen sind sehr wichtig und weisen einige wesentliche Unterschiede auf:

Tutorials-Dokumentation: Bei dieser Art von Dokumentation handelt es sich um eine informationsbasierte Dokumentation, die auf die Schulung ausgerichtet ist.

How-To Guides/User Guides Dokumentation: Benutzerhandbücher sind Dokumentationen, in denen beschrieben wird, wie bestimmte Probleme durch eine Reihe von Schritten gelöst werden können, um ein bestimmtes Ziel zu erreichen.

Erläuterungsdokumentation: Dabei handelt es sich um eine artikelartige Dokumentation, die dem Benutzer/Leser durch verschiedene Erklärungen und Hintergrundinformationen ein tieferes Verständnis eines Produkts vermitteln soll.

Referenzdokumentation: Diese Dokumentation dient dazu, den Benutzer über die Beschreibung verschiedener neuer Funktionen und deren Verwendung zu informieren. Diese Art von Dokumentation kann in Form von Entwicklerdokumentation sehr "roh" sein, sie kann jedoch auch in benutzerfreundlichere Versionshinweise übersetzt werden, die für den Endbenutzer leicht verständlich sind.

Gründe für die Erstellung einer hochwertigen Dokumentation

Bevor wir fortfahren, ist es wichtig zu verstehen, warum die Erstellung einer kompetenten Dokumentation in der heutigen Gesellschaft eine sehr wichtige, aber unterschätzte Notwendigkeit ist. Die Verfügbarkeit einer umfangreichen und gut geschriebenen Dokumentation ist eines der wichtigsten Kriterien, um eine breite Akzeptanz zu erreichen, insbesondere bei Open-Source-Projekten, bei denen praktisch jede Aktion öffentlich zugänglich ist und wo solche Aktivitäten eine entscheidende Rolle für den Erfolg des Projekts spielen.

Werfen wir einen Blick auf die wichtigsten Gründe für das Schreiben einer effektiven Dokumentation.

Sie ermöglicht es Ihnen, Ihren Kunden einen besseren Einstieg in das Projekt zu ermöglichen.

Wenn Sie Ihren Kunden eine angemessene Dokumentation über Ihr Produkt zur Verfügung stellen, helfen Sie ihnen, sich mit Ihrem Produkt wohler zu fühlen und sich durch seine spezifischen Richtlinien zu schützen. Um dies zu erreichen, müssen Sie Folgendes tun:

1. Stellen Sie sicher, dass Ihre Produktdokumentation sichtbar und leicht zugänglich ist, entweder über In-App-Links oder über eine durchsuchbare Dokumentationsplattform.

2. Stellen Sie sicher, dass sie gut geschrieben sind und dem Kunden helfen, seine Antwort schnell und einfach zu finden.

Ein Ratschlag lautet: Schreiben Sie Ihre Dokumentation nur einmal, und sie wird immer wieder zur Hand genommen, wenn neue Kunden in Ihr Unternehmen kommen.

Das hat zur Folge, dass es weniger Support-Anfragen gibt.

Kunden, die Ihre Dokumentation lesen und verstehen, kaufen mit größerer Wahrscheinlichkeit auch Ihre Produkte. Wenn Kunden nicht in der Lage sind, etwas herauszufinden, kann das sehr ärgerlich sein, und sie fangen vielleicht an, Ihrem Produkt die Schuld zu geben.

Manche Kunden wenden sich sofort an den Kundendienst oder schicken eine E-Mail, wenn sie auf ein Problem stoßen. Wenn die Dokumentation jedoch ansprechend, leicht zugänglich und verständlich ist, können sie ihre Probleme selbst lösen, ohne sich an Sie wenden zu müssen, was wiederum dazu führt, dass sie sich stärker in die Verantwortung genommen fühlen.

Es hilft Ihnen, Ihr eigenes Team zu unterstützen.

Eine solide Wissensdatenbank kann auch zur Unterstützung Ihrer eigenen Teammitglieder verwendet werden. So sollte Ihr internes Team über neue Funktionen, geplante Roadmaps, API-Dokumentation und alles andere, was notwendig ist, damit alle auf dem gleichen Stand sind, informiert werden.

Schritt-für-Schritt-Anleitung für das Verfassen einer effektiven Dokumentation

Das Verfassen des Inhalts des Dokuments und die Organisation dieser Tätigkeit sind zwei völlig verschiedene Aufgaben, die sich von der Festlegung des richtigen Tons und der Sicherstellung der Verständlichkeit Ihrer Dokumentation unterscheiden. Laut [O'Reilly gibt es 8 Regeln für eine ausgezeichnete Dokumentation] (https://www.oreilly.com/content/the-eight-rules-of-good-documentation/):

1. **Erstellen Sie eine Dokumentation, die für den Leser einladend ist.

2. **Erstellen Sie eine gründliche Dokumentation, die alle Bereiche des Projekts abdeckt.

3. **3. Erstellen Sie leicht verständliche und überschaubare Unterlagen.

4. **Erstellen Sie eine Dokumentation, die anhand von Fallstudien zeigt, wie das Produkt verwendet werden kann.

5. **Schreiben Sie eine Dokumentation, die Wiederholungen enthält, wo sie notwendig sind.

6. Schreiben Sie eine Dokumentation, die auf dem neuesten Stand ist.

7. Schreiben Sie eine Dokumentation, zu der man einfach beitragen kann

8. Schreiben Sie eine Dokumentation, die einfach zu entdecken und zu verstehen ist

Diese Elemente beziehen sich hauptsächlich auf den Inhalt. Im Anschluss daran gehen wir in sechs Schritten auf das "Wie" der Strukturierung dieser Informationen ein:

Entscheiden Sie, was Sie aufzeichnen sollen.

Nehmen Sie sich etwas Zeit, um zu überlegen, welche Art von Dokumentation Sie erstellen werden, bevor Sie beginnen: Handelt es sich um eine Anleitung, ein Referenzdokument, eine Gebrauchsanweisung oder eine Erklärung?

Beachten Sie, dass die Art Ihres Produkts einen direkten Einfluss auf die Art der Dokumentation hat, die Sie erstellen sollen.

Erstellen Sie einen Rahmen.

Schaffen Sie zunächst eine Grundlage für Ihre Dokumentation. Dies kann zu Beginn etwas sehr Kleines sein und nur einige wenige Gruppen umfassen, aber mit der Zeit wird die gesamte Plattform, auf der Sie aufbauen, immer größer und komplexer werden. Sie sollten Ihre Organisationsstruktur in regelmäßigen Abständen überprüfen.

Denken Sie daran, dass Sie die Lehrkraft sind und letztlich dafür verantwortlich sind, wie Ihre Schüler in Ihrem Unterricht lernen. Je mehr Zeit Sie für die Strukturierung aufwenden, desto erfolgreicher werden Ihre Schüler in ihren Bemühungen sein.

Nutzen Sie immer die Vorteile solider Multimedia-Techniken.

Achten Sie darauf, dass Sie Videos, Zeichnungen und verschiedene Stile verwenden und sie direkt in Ihre Dokumentation einbinden. Docsie ermöglicht die Einbettung all dieser Elemente in unsere Plattform, um diesen Prozess zu vereinfachen.

Sie helfen nicht nur den Verbrauchern, die Informationen besser zu verstehen, die Sie zum Ausdruck bringen, sondern bieten auch eine fantastische Suchmaschinenoptimierung, die zu einer größeren Anzahl hochwertiger Leads als Ergebnis Ihrer dynamischen Dokumentation führen wird.

Stellen Sie sicher, dass sie durchsuchbar ist.

Es gibt Unterschiede in den Suchfunktionen der verschiedenen Wissensdatenbank-Plattformen - einige bieten nur eine einfache Suche ohne die Möglichkeit, in Segmenten zu suchen (was technisch in Ordnung ist, wenn Sie nicht Tausende von Dateien haben), während andere Abfrageoptionen bieten, die es Ihnen ermöglichen, nicht nur in Dokumenten, sondern auch in Benutzernamen zu suchen.

Eines ist jedoch entscheidend: Sie sollten ein Tool verwenden, mit dem Sie schnell suchen können. Eine in die App integrierte Suchfunktion macht es einfach, nach Dateien zu suchen und eine Vorschau zu erhalten, ohne die App zu verlassen.

Docsie ermöglicht Ihnen eine dynamisch durchsuchbare Navigation für leicht zugängliche Informationen.

Ständiges Streben nach Verbesserung und Aktualisierung

Die Erstellung und Nutzung von Dokumenten ist schwierig, da sie von den Personen, die sie erstellt oder von ihnen profitiert haben, schnell vergessen werden. Außerdem sind Dokumente auf ihrem Weg mit einer Reihe von Herausforderungen konfrontiert.

Im Laufe der Zeit nimmt die Ordnerstruktur das Aussehen eines Friedhofs an, da ältere Dokumente dazu neigen, an einer unteren Position des Bildschirms zu bleiben.

Gehen Sie also auf jeden Fall noch einmal durch Ihre alte Dokumentation und nehmen Sie Verbesserungen vor, und ermutigen Sie auch Ihre Kollegen, dies von Zeit zu Zeit zu tun. Docsie ermöglicht es Ihnen, Aktualisierungen durch unser fortschrittliches Versionierungssystem zu erstellen, das einfach und leicht zu handhaben ist.

Abschließende Gedanken:

Möchten Sie mehr darüber wissen, wie man eine effektive Dokumentation schreibt? Für Fachleute im Bereich Software-Dokumentation gibt es hier eine Fülle von Blogs und Informationen zu finden.