Was ist Software-Dokumentation? Typen und Best Practices für den Einstieg

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

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

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

Legen wir los!

Was ist Software-Dokumentation?

Software-Dokumentation ist Inhalt, der Endbenutzern, Entwicklern und/oder Ihren Mitarbeitern hilft, Ihre Software zu verstehen und sie effektiv zur Erreichung ihrer Ziele einzusetzen.

Typischerweise veröffentlichen Sie die Software-Dokumentation auf Ihrer Website. Personen können dann darauf zugreifen, um mehr über Ihre Software und ihre Funktionsweise zu erfahren.

Innerhalb dieser breiten Definition von Software-Dokumentation gibt es verschiedene Arten von Software-Dokumentation. Lassen Sie uns das als Nächstes besprechen.

Die verschiedenen Arten von Software-Dokumentation

Sie können die verschiedenen Arten von Software-Dokumentation grob in einige breite Kategorien einteilen.

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

• Benutzerdokumentation – dies ist eine Dokumentation, die Sie für den Endbenutzer des Produkts erstellt haben. Sie hilft ihm zu verstehen, wie er Ihre Software aus der Perspektive eines normalen Benutzers verwendet, der möglicherweise über spezielles technisches Wissen verfügt oder auch nicht.
• Entwicklerdokumentation – dies ist eine technischere Software-Dokumentation, die Sie für Entwickler erstellt haben, z. B. API-Dokumentation.

Die zweite Überlegung ist, ob die Dokumentation für externe oder interne Zielgruppen bestimmt ist:

• Externe Software-Dokumentation – dies ist eine öffentlich zugängliche Dokumentation, die Sie erstellt haben, um Ihren Benutzern zu helfen.
• Interne Software-Dokumentation – dies ist eine private Dokumentation, die Sie für Ihre Mitarbeiter erstellt haben, um ihnen zu helfen, effektiver zu arbeiten und wichtige Details zu verstehen. (Umfassender Leitfaden zur internen Dokumentation)

Zum Beispiel könnten Sie einen Satz von Entwicklerdokumentationen für Ihre internen Teams haben, um bei der Arbeit an der Software zu helfen, und einen weiteren Satz von öffentlich zugänglichen Entwicklerdokumentationen für externe Entwickler.

Lassen Sie uns diese Arten von Software-Dokumentationen etwas genauer aufschlüsseln...

Beispiele für Software-Dokumentationen für Entwickler

• API-Dokumentation – zeigt Entwicklern, wie sie mit der API Ihrer Software interagieren können.
• Readme – stellt Ihre Software vor und erklärt, was sie tut – normalerweise das Erste, was die Leute lesen.
• Release Notes – dokumentieren neue Versionen Ihrer Software, einschließlich wichtiger Änderungen.
• Architektur-Dokumentation – zeigt die Struktur Ihrer Software, möglicherweise einschließlich Diagrammen.
• Datenmodell-Dokumentation – dokumentiert die verschiedenen Datenstrukturen in Ihrer Software, einschließlich der Beziehungen zwischen verschiedenen Datenstrukturen.
• Prozess-Dokumentation – dokumentiert Schlüsselprozesse wie Fehlerberichte, Roadmaps, Qualitätssicherung, Testprotokolle und so weiter.

Als echtes Beispiel für softwarebezogene Entwicklerdokumentationen können Sie sich die „Entwickler“-Dokumentation von Gravity Forms ansehen, die verschiedene Themen abdeckt, wie zum Beispiel:

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

Zum Beispiel sieht die REST-API-Dokumentation so aus:

Software-Dokumentationsbeispiele für Benutzerdokumentation

• Erste Schritte-Anleitung – zeigt Benutzern, wie sie schnell mit Ihrer Software loslegen können.
• Tutorials für spezifische Anwendungsfälle – spezifischere Tutorials zur Erledigung bestimmter Aufgaben.
• Terminologielisten/Referenzhandbücher – helfen Benutzern, Schlüsselbegriffe und Details zu verstehen. Wir haben eine Anleitung zur Erstellung eines Glossars mit WordPress, wenn Sie mehr erfahren möchten.
• FAQs – beantworten häufig gestellte Fragen.

Ein reales Beispiel dafür, wie benutzerorientiertere Software-Dokumentation aussehen könnte, finden Sie im obigen Gravity Forms-Beispiel.

Wenn Sie sich die benutzerorientierteren Artikel von Gravity Forms ansehen, sehen Sie viele Schritt-für-Schritt-Anleitungen, wie Sie Aufgaben mit der Software-Oberfläche erledigen können, zusammen mit Glossaren und Erklärungen wichtiger Funktionen.

Im Vergleich zu Entwickler-Software-Dokumentation sehen Sie mehr Screenshots und Erklärungen in einfacher Sprache und viel weniger Codeblöcke.

So veröffentlichen Sie Software-Dokumentationen: Drei beste Tools für Software-Dokumentationen

Um Ihre Software-Dokumentation auf Ihrer Website zu veröffentlichen, benötigen Sie ein spezielles Tool für Software-Dokumentationen oder eine Art Wissensmanagementsystem.

In diesem Abschnitt werden wir einige der besten Tools für Software-Dokumentationen kurz vorstellen. Anschließend gehen wir im nächsten Abschnitt auf einige Best Practices für die Erstellung qualitativ hochwertiger Dokumentationen ein.

Wenn Sie hier tiefer eintauchen möchten, lesen Sie unsere vollständigen Anleitungen zu den besten Dokumentationstools und der besten Software für technische Dokumentationen.

Heroic Knowledge Base

Heroic Knowledge Base ist ein Plugin für Dokumentation und Wissensdatenbank 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 dennoch auf alle Funktionen zugreifen können, die Sie für die Erstellung effektiver Software-Dokumentationen benötigen.

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

• Flexibler Inhaltseditor, einschließlich integrierter Blöcke für Callouts und andere wichtige Stil-Details.
• Automatisches Inhaltsverzeichnis, damit Benutzer schnell sehen können, welche Inhalte in einem Dokumentationsartikel behandelt werden, und zu bestimmten Abschnitten springen können.
• Revisionskontrolle und Versionsverlauf über das native WordPress-Revisionssystem.
• Funktionen zur Inhaltsfindung, einschließlich Echtzeit-Ajax-Suche mit Live-Vorschlägen, Kategorien und mehr.
• Benutzerfeedback-System, mit dem Benutzer Artikel als hilfreich oder nicht hilfreich bewerten und Feedback teilen können.
• Suchanalysen, damit Sie sehen können, wonach Benutzer suchen, sowie alle Suchbegriffe, die null Ergebnisse liefern.
• Widget für Sofortantworten, damit Benutzer von überall auf Ihrer Website nach Software-Dokumentationen suchen und darauf zugreifen können.

Da Heroic Knowledge Base und WordPress beide selbst gehostet und Open-Source sind, können Sie Ihr Setup auch nach Bedarf ändern.

Sie können es öffentlich zugänglich machen oder den Zugriff auf Ihre Dokumentation einschränken mit verschiedenen Taktiken wie Passwörtern, Benutzerkonten, IP-Adressen, einem Intranet und mehr.

Heroic Knowledge Base ist ab nur 67 US-Dollar pro Jahr erhältlich.

Read the Docs

Read the Docs ist ein Dokumentationstool, das sich darauf konzentriert, Ihnen bei der Erstellung von Entwicklerdokumentationen zu helfen.

Wenn Sie sich speziell auf die Erstellung technischer Entwicklerdokumentationen konzentrieren, kann dies eine weitere gute Option sein, die Sie in Betracht ziehen sollten.

Sie können Ihre Inhalte und die Revisionshistorie mit Git verwalten und Ihre Dokumente dann auf einer Frontend-Oberfläche bereitstellen.

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

• Integrierte Analysen, um zu sehen, was Ihre Benutzer lesen und wonach sie suchen.
• Unterstützt mehrere gleichzeitige Builds, was hilfreich sein kann, wenn Sie mehrere Versionen Ihrer Software anbieten – z. B. ein Satz von Dokumentationen für Version 1.0 und ein anderer für Version 2.0.
• Exportieren Sie Dokumentationen in verschiedenen Formaten, einschließlich PDF, HTML und epub.
• Live-Suchvorschläge, die Benutzern helfen, Dokumente zu finden.

Read the Docs ist eine kostenlose Open-Source-Dokumentationssoftware.

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

GitBook

GitBook ist ein weiteres Tool für technische Softwaredokumentation, mit dem Sie Ihre Dokumentation mithilfe von Git verwalten können, mit Unterstützung für GitHub- und GitLab-Repositories.

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

Hier sind einige weitere bemerkenswerte Funktionen, die GitBook bietet:

• Versionskontrolle, um Überarbeitungen und die Versionshistorie zu verfolgen.
• Live-Team-Bearbeitung, was hilfreich ist, wenn mehrere Autoren an Artikeln zusammenarbeiten müssen.
• Organisieren Sie Artikel mithilfe von „Spaces“ und „Collections“ – jeder Space kann mehrere Collections enthalten.
• PDF-Export Option, damit Benutzer Ihre Dokumentation einfach als PDF-Download exportieren können.

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

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

Best Practices für die Erstellung von Software-Dokumentation

Um die Sache abzurunden, befassen wir uns mit einigen Best Practices für die Software-Dokumentation, die Ihnen helfen, effektive Dokumentation zu erstellen.

Denken Sie über die Ziele und Bedürfnisse der Benutzer nach

Wenn Sie einen Artikel für die Software-Dokumentation schreiben, ist es wichtig, mit der Beantwortung einiger grundlegender Fragen zu beginnen:

• Für wen schreiben Sie?
• Was versucht der Benutzer zu erreichen?
• Welches technische Wissen hat der Benutzer?

Die Antworten auf diese Fragen helfen Ihnen zu verstehen, welche Inhalte Sie behandeln und wie Sie den Artikel am besten strukturieren.

Nehmen wir zum Beispiel an, Sie bieten eine Software zur Planung von Social-Media-Posts an und schreiben einen Artikel, der Social-Media-Managern hilft, ihren ersten Social-Media-Post zu planen.

Beim Schreiben Ihrer Software-Dokumentation möchten Sie sich darauf konzentrieren, dem normalen Endbenutzer den einfachsten Weg zu zeigen, um dieses Ziel zu erreichen.

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

Software-Dokumentation in den Entwicklungsprozess einbeziehen

Wenn Sie Software-Dokumentation erstellen, ist es leicht, in die Falle zu tappen, bis ein Projekt abgeschlossen ist, um es zu dokumentieren.

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

Um dies zu vermeiden, machen Sie die Software-Dokumentation zu einem bewussten Teil des Softwareentwicklungszyklus. Wenn eine neue Funktion oder ein neues Produkt noch nicht dokumentiert wurde, ist es noch nicht versandbereit, auch wenn der Code selbst fertig ist.

Indem Sie die Dokumentation zu einer Kernanforderung des Softwareentwicklungsprozesses machen, können Sie sicherstellen, dass alles, was Sie ausliefern, mit der entsprechenden Dokumentation versehen ist.

Einheitliche Formatierung und Stil verwenden

Um den Menschen die effektivere Arbeit mit Ihrer Software-Dokumentation zu erleichtern, ist es wichtig, dass Sie über die gesamte Dokumentation hinweg eine einheitliche Formatierung und einen einheitlichen Stil verwenden.

Die Verwendung derselben Formatierung ermöglicht es den Lesern, die Struktur Ihrer Software-Dokumentation zu erlernen, was es ihnen erleichtert, schnell auf die benötigten Informationen zuzugreifen.

Um diese Konsistenz zu erreichen, möchten Sie vielleicht einen speziellen Dokumentationsstil-Leitfaden erstellen.

Ihr Tool zur Verwaltung von Software-Dokumentationen kann auch Funktionen enthalten, die Ihnen helfen, eine konsistente Formatierung zu erreichen.

Zum Beispiel enthält das Heroic Knowledge Base Plugin vorformatierte Callouts, um wichtige Informationen oder Warnungen hervorzuheben. Durch deren Verwendung können Sie eine konsistente Formatierung über Ihre gesamte Dokumentation hinweg sicherstellen.

Experten für die Erstellung technischer Dokumentation einsetzen

Für benutzerorientierte Software-Dokumentation benötigen Sie möglicherweise keine Fachexperten, um den Inhalt zu schreiben.

Für technischere Software-Dokumentationen, wie z. B. API-Dokumentationen für Entwickler, möchten Sie wahrscheinlich jemanden mit dem entsprechenden technischen Wissen beauftragen, diese Dokumente zu verfassen.

Dies könnte ein engagierter technischer Redakteur mit Branchenkenntnissen sein, wenn Ihr Unternehmen über die Ressourcen verfügt, diese Stelle zu besetzen. Oder es könnte einer Ihrer Entwickler sein.

Wichtig ist, dass der Autor die technischen Aspekte Ihrer Software auf einem ausreichend tiefen Niveau versteht, um sie anderen technischen Benutzern erklären zu können.

Machen Sie es den Leuten leicht, Inhalte zu finden (Suche/Filter)

Wenn Ihre Dokumentationsbibliothek wächst, wird es für Benutzer schwieriger, die Dokumentationsartikel zu finden, die ihren Bedürfnissen entsprechen.

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

Eine erste Strategie ist, Ihre Dokumentation nach Typ zu unterteilen.

Zum Beispiel möchten Sie in der Regel Ihre Endbenutzer-Dokumentation von der Entwickler-Software-Dokumentation trennen.

Innerhalb dessen können Sie auch Kategorien verwenden, um Artikel weiter zu unterteilen. Sie können Kategorien basierend auf Funktionen, Anwendungsfällen, Add-ons usw. verwenden – was auch immer für Ihr Softwareprodukt logisch sinnvoll ist.

Im Einklang mit dem obigen Gravity Forms-Beispiel sehen Sie, dass Gravity Forms seine Endbenutzer-Dokumentation nach Feature-Typen unterteilt.

Eine weitere nützliche Funktion zur Verbesserung der Auffindbarkeit sind Live-Suchvorschläge. Benutzer können eine relevante Abfrage in das Suchfeld eingeben und sofort Dokumentationsartikel sehen, die dieser Abfrage entsprechen.

Viele Dokumentationstools beinhalten eine integrierte Live-Suchfunktion, darunter Heroic Knowledge Base.

Halten Sie Ihre Software-Dokumentation aktuell

Da sich Ihre Software ständig ändert, wird Ihre Software-Dokumentation immer ein Werk im Entstehen sein.

Wenn sich Dinge in Ihrer Software ändern, müssen Sie Ihre Dokumentation umgehend aktualisieren, um diese Änderungen widerzuspiegeln.

Andernfalls wird Ihre Dokumentation nicht nur „nicht hilfreich“ sein, sondern kann Ihre Benutzer tatsächlich verwirren.

Um sicherzustellen, dass diese Aktualisierungen erfolgen, sollten Sie bestimmte Personen für die Dokumentation und den Aktualisierungsprozess benennen. Auf diese Weise gibt es keine Unklarheiten darüber, wer für die Genauigkeit verantwortlich ist.

Nutzen Sie Kundenfeedback zur Verbesserung Ihrer Dokumentation

Zusätzlich zur Überprüfung und Aktualisierung Ihrer Software-Dokumentation durch Ihr eigenes Team sollten Sie auch Kundenfeedback berücksichtigen.

Kunden können wertvolle Informationen darüber liefern, wie hilfreich (oder potenziell unhilfreich) ein bestimmter Dokumentationsartikel ist, sowie Details dazu, wie Sie ihn verbessern könnten.

Um den Prozess für Kundenfeedback zu automatisieren, sollten Sie nach einem Dokumentationsverwaltungstool suchen, das integrierte Funktionen für Kundenfeedback bietet.

Zum Beispiel ermöglicht das Heroic Knowledge Base Plugin den Benutzern, einen Artikel als hilfreich oder nicht hilfreich zu bewerten und optional auch Freitext-Feedback zu geben.

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

Beginnen Sie noch heute mit der Dokumentation Ihrer Software

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

Es gibt verschiedene Arten von Software-Dokumentation, daher sollten Sie überlegen, welche Arten den Bedürfnissen Ihres Softwareprojekts entsprechen.

Möglicherweise haben Sie unterschiedliche Dokumentationen für interne oder externe Teams sowie für verschiedene Kundentypen, z. B. Entwickler im Vergleich zu Endbenutzern.

Um eine effektive Dokumentation zu erstellen, sollten Sie die Best Practices aus diesem Beitrag befolgen.

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

Sie erhalten die Flexibilität und den Besitz einer selbst gehosteten Plattform mit allen Funktionen und der Funktionalität, die Sie für die Veröffentlichung hochwertiger Software-Dokumentation benötigen.