Was ist Software-Dokumentation? Arten und beste Praktiken für den Einstieg

Wenn Sie möchten, dass Entwickler und Endbenutzer den größtmöglichen Nutzen aus Ihrer Software ziehen, müssen Sie eine hochwertige Softwaredokumentation erstellen.

Aber was ist eigentlich eine Software-Dokumentation, und wie können Sie sie für Ihr Projekt erstellen?

In diesem Beitrag gehen wir auf alles ein, was Sie über Software-Dokumentation wissen müssen, einschließlich der folgenden Punkte:

Auf geht's!

Was ist Software-Dokumentation?

Software-Dokumentation ist der Inhalt, der den Endbenutzern, Entwicklern und/oder Ihren Mitarbeitern hilft, Ihre Software zu verstehen und sie effektiv zu nutzen, um ihre Ziele zu erreichen.

Normalerweise veröffentlichen Sie die Software-Dokumentation auf Ihrer Website. Die Benutzer können dann darauf zugreifen, um mehr über Ihre Software und deren Funktionsweise zu erfahren.

Innerhalb dieser weit gefassten Definition von Software-Dokumentation gibt es verschiedene Arten von Software-Dokumentation. Lassen Sie uns das als nächstes diskutieren.

Die verschiedenen Arten der Software-Dokumentation

Man kann die verschiedenen Arten von Software-Dokumentation grob in einige wenige Kategorien einteilen.

Die erste Überlegung ist, für welche Art von Person die Dokumentation bestimmt ist:

• Benutzerdokumentation - dies ist die Dokumentation, die Sie für den Endbenutzer des Produkts erstellt haben. Sie hilft ihnen zu verstehen, wie sie Ihre Software aus der Sicht eines normalen Benutzers verwenden können, der vielleicht keine besonderen technischen Kenntnisse hat.
• Entwicklerdokumentation - dies ist eine eher technische Softwaredokumentation, die Sie für Entwickler erstellt haben, z. B. eine API-Dokumentation.

Die zweite Überlegung ist, ob die Dokumentation für ein externes oder internes Publikum bestimmt ist:

• Externe Software-Dokumentation - dies ist die öffentlich zugängliche Dokumentation, die Sie zur Unterstützung Ihrer Benutzer erstellt haben.
• Interne Software-Dokumentation - dies ist eine private Dokumentation, die Sie für Ihre Mitarbeiter erstellt haben, damit diese effektiver arbeiten und wichtige Details verstehen können.(Vollständiger Leitfaden zur internen Dokumentation)

Sie könnten zum Beispiel einen Satz an Entwicklerdokumentation für Ihre internen Teams haben, die an der Software arbeiten, und einen anderen Satz an öffentlich zugänglicher Entwicklerdokumentation für externe Entwickler.

Lassen Sie uns diese Arten von Software-Dokumentation ein wenig detaillierter aufschlüsseln...

Software-Dokumentationsbeispiele für Entwicklerdokumentation

• API-Dokumentation - zeigt Entwicklern, wie sie mit der API Ihrer Software interagieren können.
• Liesmich - stellt Ihre Software vor und erklärt, was sie tut - normalerweise das erste, was die Leute lesen.
• Versionshinweise - dokumentieren neue Versionen Ihrer Software, einschließlich aller wichtigen Änderungen.
• Architektur-Dokumentation - zeigt die Struktur Ihrer Software, möglicherweise mit Diagrammen.
• Datenmodelldokumentation - Dokumentieren Sie die verschiedenen Datenstrukturen in Ihrer Software, einschließlich der Beziehungen zwischen verschiedenen Datenstrukturen.
• Prozessdokumentation - Dokumentieren Sie die wichtigsten Prozesse wie Fehlerberichte, Roadmaps, Qualitätssicherung, Testprotokolle und so weiter.

Ein Beispiel für eine echte Software-Dokumentation, die sich an Entwickler richtet, ist die Gravity Forms-Dokumentation für Entwickler, die verschiedene Themen abdeckt, z. B:

• PHP-Haken (für WordPress)
• Datenobjekte
• PHP-API
• Datenbank
• REST-API

Die REST-API-Dokumentation sieht zum Beispiel so aus:

Software-Dokumentation Beispiele für Benutzerdokumentation

• Leitfaden für die ersten Schritte - zeigen Sie den Benutzern, wie sie Ihre Software schnell in Betrieb nehmen können.
• Tutorials für bestimmte Anwendungsfälle - spezifischere Tutorials für die Durchführung bestimmter Aufgaben.
• Begriffsglossare/Referenzhandbücher - helfen den Benutzern, wichtige Begriffe und Details zu verstehen. Wir haben einen Leitfaden zur Erstellung von Glossaren mit WordPress, wenn Sie mehr erfahren möchten.
• FAQs - Antworten auf häufig gestellte Fragen.

Ein konkretes Beispiel dafür, wie eine stärker benutzerorientierte Softwaredokumentation aussehen könnte, finden Sie in dem oben genannten Beispiel für Gravity Forms.

In den Artikeln zu Gravity Forms, die sich mehr an die Benutzer richten, finden Sie viele Schritt-für-Schritt-Anleitungen, die Ihnen zeigen, wie Sie Aufgaben über die Software-Oberfläche erledigen können, sowie Glossare und Erklärungen zu wichtigen Funktionen.

Im Vergleich zur Dokumentation von Entwicklersoftware werden Sie mehr Screenshots und Erklärungen in einfacher Sprache und viel weniger Codeblöcke sehen.

Wie man Software-Dokumentation veröffentlicht: Die drei besten Software-Dokumentationstools

Um Ihre Software-Dokumentation auf Ihrer Website zu veröffentlichen, benötigen Sie ein spezielles Software-Dokumentationstool oder eine Art Wissensmanagementsystem.

In diesem Abschnitt werden wir kurz einige der besten Software-Dokumentationstools vorstellen. Im nächsten Abschnitt gehen wir dann auf einige bewährte Verfahren für die Erstellung hochwertiger Dokumentation ein.

Wenn Sie sich eingehender mit diesem Thema befassen möchten, sollten Sie unsere ausführlichen Leitfäden über die besten Dokumentationswerkzeuge und die beste Software für technische Dokumentation lesen.

Heldenhafte Wissensbasis

Heroic Knowledge Base ist ein Dokumentations- und Wissensdatenbank-Plugin für die beliebte Open-Source-Software WordPress.

Mit Heroic Knowledge Base können Sie Ihre Dokumentation selbst hosten und die volle Kontrolle behalten, während Sie gleichzeitig auf alle Funktionen zugreifen können, die Sie für die Erstellung einer effektiven Software-Dokumentation benötigen.

Hier sind einige der wichtigsten Funktionen, die Sie mit der Heroic Knowledge Base erhalten:

• Flexibler Inhaltseditor, einschließlich integrierter Blöcke für Beschriftungen und andere wichtige Stildetails.
• Automatisches Inhaltsverzeichnis, damit die Benutzer schnell sehen können, welche Inhalte in einem Dokumentationsartikel behandelt werden und zu bestimmten Abschnitten springen können.
• Revisionskontrolle und Versionsgeschichte über das native WordPress-Revisionssystem.
• Funktionen zum Auffinden von Inhalten, einschließlich Echtzeit-Ajax-Suche mit Live-Vorschlägen, Kategorien und mehr.
• Benutzer-Feedback-System, mit dem die Nutzer Artikel als hilfreich oder nicht hilfreich bewerten und ihr Feedback weitergeben können.
• Suchanalysen , damit Sie sehen können, wonach die Nutzer suchen, und welche Suchbegriffe keine Ergebnisse liefern.
• Ein Widget für Sofortantworten, mit dem Benutzer von überall auf Ihrer Website aus nach Software-Dokumentation suchen und darauf zugreifen können.

Da Heroic Knowledge Base und WordPress beide selbst gehostet werden und Open-Source sind, können Sie Ihre Einrichtung nach Bedarf ändern.

Sie können es öffentlich zugänglich machen oder den Zugang zu Ihrer Dokumentation durch verschiedene Maßnahmen wie Passwörter, Benutzerkonten, IP-Adressen, ein Intranet usw. einschränken.

Die Heroic Knowledge Base kostet nur $149 pro Jahr.

Lesen Sie die Dokumente

Read the Docs ist ein Dokumentationswerkzeug, das Sie bei der Erstellung von Entwicklerdokumentation unterstützt.

Wenn Sie sich speziell auf die Erstellung technischer Entwicklerdokumentation konzentrieren, kann dies eine weitere gute Option sein.

Sie können Ihre Inhalte und den Revisionsverlauf mit Git verwalten und Ihre Dokumente dann auf einer Frontend-Schnittstelle bereitstellen.

Hier sind einige der anderen bemerkenswerten Funktionen von Read the Docs:

• Integrierte Analysen, um zu sehen, was Ihre Nutzer lesen und wonach sie suchen.
• Unterstützt mehrere gleichzeitige Builds, was hilfreich sein kann, wenn Sie mehrere Versionen Ihrer Software anbieten - z.B. einen Satz Dokumentation für Version 1.0 und einen anderen für Version 2.0.
• Exportieren Sie die Dokumentation in verschiedenen Formaten wie PDF, HTML und epub.
• Live-Suchvorschläge, die den Nutzern das Auffinden von Dokumenten erleichtern.

Read the Docs ist kostenlos, wenn Sie ein Open-Source-Softwareprojekt haben.

Für kommerzielle Softwareprodukte gibt es einen kostenpflichtigen Read the Docs for Business-Service, der bei 50 Dollar pro Monat beginnt.

GitBook

GitBook ist ein weiteres Tool für die technische Softwaredokumentation, mit dem Sie Ihre Dokumentation mithilfe von Git verwalten können, wobei sowohl GitHub- als auch GitLab-Repositories unterstützt werden.

Wenn Sie Git nicht verwenden möchten, können Sie mit GitBook Ihre Dokumentation auch mit einem Texteditor erstellen oder aus Markdown- oder .doc-Dateien importieren.

Hier sind einige weitere bemerkenswerte Funktionen, die GitBook bietet:

• Versionskontrolle zur Verfolgung von Revisionen und Versionsverlauf.
• Live-Team-Bearbeitung , die hilfreich ist, wenn mehrere Autoren an Artikeln zusammenarbeiten müssen.
• Organisieren Sie Artikel mithilfe von "Bereichen" und "Sammlungen" - jeder Bereich kann mehrere Sammlungen enthalten.
• PDF-Exportoption , so dass die Benutzer Ihre Dokumentation einfach als PDF-Download exportieren können.

GitBook ist für gemeinnützige Organisationen und Open-Source-Projekte kostenlos.

Für kommerzielle Softwareprojekte beginnt GitBook bei $8 pro Benutzer und Monat, bei einem Minimum von 5 Benutzern. Das bedeutet, dass der günstigste monatliche Tarif 40 $ pro Monat beträgt.

Best Practices für die Erstellung von Software-Dokumentation

Lassen Sie uns zum Abschluss noch einige Best Practices für die Software-Dokumentation durchgehen, die Ihnen bei der Erstellung einer effektiven Dokumentation helfen.

Denken Sie an die Ziele und Bedürfnisse der Nutzer

Wenn Sie einen Artikel zur Software-Dokumentation schreiben, sollten Sie zunächst einige grundlegende Fragen beantworten:

• Wer ist der Benutzer, für den Sie schreiben?
• Was will der Benutzer erreichen?
• Über welche technischen Kenntnisse verfügt der Nutzer?

Wenn Sie die Antworten auf diese Fragen kennen, wissen Sie, welche Inhalte Sie behandeln und wie Sie den Artikel optimal strukturieren sollten.

Nehmen wir an, Sie bieten Software für die Planung von Social Media an und schreiben einen Artikel, der Social Media-Managern hilft, ihren ersten Social Media-Post zu planen.

Wenn Sie Ihre Software-Dokumentation schreiben, sollten Sie sich darauf konzentrieren, den einfachsten Weg aufzuzeigen, wie ein normaler Endbenutzer das Ziel erreichen kann.

Wenn Sie auch eine API anbieten, über die Entwickler ihre eigenen Integrationen einrichten können, sollten Sie dies wahrscheinlich in einem anderen Artikel behandeln(obwohl Sie diese Methode erwähnen und verlinken könnten).

Software-Dokumentation in den Entwicklungsprozess einbeziehen

Bei der Erstellung von Software-Dokumentation tappt man leicht in die Falle, zu warten, bis ein Projekt abgeschlossen ist, um es zu dokumentieren.

Dies kann jedoch schnell zu Dokumentationsschulden führen, da Sie neue Funktionen oder Änderungen ausliefern, bevor sie dokumentiert wurden.

Um dies zu vermeiden, sollten Sie die Softwaredokumentation zu einem festen Bestandteil des Softwareentwicklungszyklus machen. Wenn eine neue Funktion oder ein neues Produkt noch nicht dokumentiert wurde, kann es nicht ausgeliefert werden, auch wenn der Code selbst fertig ist.

Indem Sie die Dokumentation zu einer zentralen Anforderung des Softwareentwicklungsprozesses machen, können Sie sicherstellen, dass alles, was Sie ausliefern, von einer angemessenen Dokumentation begleitet wird.

Konsistente Formatierung und Stil verwenden

Damit Ihre Mitarbeiter effektiver mit Ihrer Software-Dokumentation arbeiten können, ist es wichtig, dass Sie in Ihrer gesamten Dokumentation eine einheitliche Formatierung und einen einheitlichen Stil verwenden.

Wenn Sie die gleiche Formatierung verwenden, können die Leser lernen, wie Ihre Software-Dokumentation strukturiert ist, was es ihnen erleichtert, schnell auf die benötigten Informationen zuzugreifen.

Um diese Konsistenz zu erreichen, sollten Sie einen speziellen Leitfaden für die Software-Dokumentation erstellen.

Ihr Software-Dokumentationsmanagement-Tool kann auch Funktionen enthalten, die Ihnen helfen, ein einheitliches Styling zu erreichen.

Das Heroic Knowledge Base Plugin enthält zum Beispiel vorgefertigte Callouts, um wichtige Informationen oder Warnungen hervorzuheben. Mit diesen können Sie eine einheitliche Formatierung Ihrer gesamten Dokumentation sicherstellen.

Experten für die Erstellung technischer Dokumentation einsetzen

Für benutzerseitige Software-Dokumentation benötigen Sie möglicherweise keine Fachleute, die den Inhalt schreiben.

Für technischere Softwaredokumentation, wie z. B. entwicklerorientierte API-Dokumentation, sollten Sie jedoch jemanden mit den entsprechenden technischen Kenntnissen mit der Erstellung dieser Dokumente beauftragen.

Dies könnte ein engagierter technischer Redakteur mit Fachkenntnissen sein, wenn Ihr Unternehmen die Ressourcen hat, um eine solche Stelle zu besetzen. Oder es könnte einer Ihrer Entwickler sein.

Wichtig ist, dass der Autor die technischen Aspekte Ihrer Software so gut versteht, dass er sie anderen technischen Benutzern erklären kann.

Erleichtern Sie das Auffinden von Inhalten (Suche/Filter)

Je größer Ihre Dokumentationsbibliothek wird, desto schwieriger wird es für die Benutzer, die Dokumentationsartikel zu finden, die ihren Bedürfnissen entsprechen.

Um dieses Problem zu vermeiden, sollten Sie sich darauf konzentrieren, die Auffindbarkeit Ihrer Software-Dokumentation zu verbessern.

Eine erste Strategie besteht darin, Ihre Dokumentation nach Typen zu unterteilen.

So werden Sie beispielsweise in der Regel Ihre Endbenutzerdokumentation von der Dokumentation für die Entwicklersoftware trennen wollen.

Dabei können Sie auch Kategorien verwenden, um die Artikel weiter zu unterteilen. Sie können Kategorien auf der Grundlage von Funktionen, Anwendungsfällen, Add-ons usw. verwenden - was immer für Ihr Softwareprodukt logisch sinnvoll ist.

In Anlehnung an das Gravity Forms-Beispiel von oben können Sie sehen, dass Gravity Forms seine Endbenutzerdokumentation nach Funktionstypen unterteilt.

Eine weitere nützliche Funktion für die Auffindbarkeit sind Live-Suchvorschläge. Die Nutzer können eine relevante Suchanfrage in das Suchfeld eingeben und bekommen sofort Dokumentationsartikel angezeigt, die dieser Anfrage entsprechen.

Viele Dokumentationswerkzeuge verfügen über eine integrierte Live-Suchfunktion, so auch die Heroic Knowledge Base.

Halten Sie Ihre Software-Dokumentation auf dem neuesten Stand

Da sich Ihre Software ständig verändert, wird auch Ihre Software-Dokumentation immer in Arbeit sein.

Wenn sich in Ihrer Software etwas ändert, müssen Sie Ihre Dokumentation umgehend aktualisieren, um diese Änderungen zu berücksichtigen.

Andernfalls ist Ihre Dokumentation nicht nur "nicht hilfreich", sondern könnte bei Ihren Benutzern sogar Verwirrung stiften.

Um sicherzustellen, dass diese Aktualisierungen durchgeführt werden, sollten Sie bestimmte Personen mit der Dokumentation und dem Aktualisierungsprozess betrauen. Auf diese Weise gibt es keine Unklarheiten darüber, wer für die Richtigkeit der Daten verantwortlich ist.

Nutzen Sie Kundenfeedback zur Verbesserung Ihrer Dokumentation

Sie sollten nicht nur Ihr eigenes Team mit der Überprüfung und Aktualisierung Ihrer Softwaredokumentation beauftragen, sondern auch das Feedback Ihrer Kunden einbeziehen.

Kunden können wertvolle Informationen darüber liefern, wie hilfreich (oder möglicherweise nicht hilfreich) ein bestimmter Artikel der Softwaredokumentation ist, sowie Details darüber, wie Sie ihn verbessern könnten.

Um den Prozess des Kundenfeedbacks zu automatisieren, sollten Sie nach einem Dokumentationsmanagement-Tool suchen, das integrierte Funktionen für Kundenfeedback enthält.

Mit dem Heroic Knowledge Base Plugin können die Nutzer beispielsweise einen Artikel als hilfreich oder nicht hilfreich bewerten und optional auch freies Feedback abgeben.

Sie können dann all diese Informationen von Ihrem Dashboard aus einsehen, um Dokumentationsartikel, die Sie verbessern müssen, schnell zu erkennen.

Dokumentieren Sie Ihre Software noch heute

Software-Dokumentation hilft Ihnen und Ihren Kunden, effektiver zu arbeiten und mehr Nutzen aus Ihrer Software zu ziehen.

Es gibt verschiedene Arten von Software-Dokumentation, so dass Sie sich überlegen sollten, welche Arten den Anforderungen Ihres Software-Projekts entsprechen.

Möglicherweise haben Sie unterschiedliche Dokumentationen für interne oder externe Teams sowie für verschiedene Arten von Kunden, z. B. Entwickler oder Endbenutzer.

Um eine effektive Dokumentation zu erstellen, sollten Sie die bewährten Verfahren aus diesem Beitrag befolgen.

Um diese Dokumentation zu veröffentlichen, können Sie ein Open-Source-Wissensdatenbank-Tool wie Heroic KBverwenden, das auf der leistungsstarken WordPress-Software basiert.

Sie erhalten die Flexibilität und das Eigentum an einer selbst gehosteten Plattform mit allen Merkmalen und Funktionen, die Sie für die Veröffentlichung hochwertiger Softwaredokumentation benötigen.