Was ist Software-Dokumentation? Plus Typen und Best Practices

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öffentlichst du die Software-Dokumentation auf deiner Website. Leute können dann darauf zugreifen, um mehr über deine Software und ihre Funktionsweise zu erfahren.

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

Innerhalb dieser breiten Definition von Software-Dokumentation gibt es verschiedene Arten von Software-Dokumentation. Lass 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 du für den Endbenutzer des Produkts erstellt hast. Sie hilft ihm zu verstehen, wie er deine Software aus der Perspektive eines normalen Benutzers verwenden kann, der möglicherweise über spezielle technische Kenntnisse verfügt oder auch nicht.
• Entwicklerdokumentation – dies ist eine technischere Software-Dokumentation, die du für Entwickler erstellt hast, 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 du erstellt hast, um deinen Benutzern zu helfen.
• Interne Software-Dokumentation – dies ist eine private Dokumentation, die du für deine Mitarbeiter erstellt hast, um ihnen zu helfen, effektiver zu arbeiten und wichtige Details zu verstehen. (Vollständiger 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.

Lass uns diese Arten von Software-Dokumentation etwas genauer aufschlüsseln…

Entdecken: 11 Arten von Kundenservice: Vollständige Anleitung mit Vor- und Nachteilen

Beispiele für Software-Dokumentationen für Entwickler

• API-Dokumentation – zeigt Entwicklern, wie sie mit der API deiner 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.
• Architekturdokumentation – zeigen Sie 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.
• Prozessdokumentation – dokumentieren Sie wichtige Prozesse wie Fehlerberichte, Roadmaps, Qualitätssicherung, Testprotokolle usw.

Als Beispiel für entwicklerorientierte Dokumente kannst du dir die „Developers“-Dokumentation von Gravity Forms ansehen, die verschiedene Themen abdeckt, wie zum Beispiel:

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

Hier ist zum Beispiel, wie die REST-API-Dokumentation aussieht:

Software-Dokumentationsbeispiele für Benutzerdokumentation

• Erste Schritte-Anleitung – zeigen Sie den Benutzern, wie sie schnell mit Ihrer Software loslegen können.
• Tutorials für spezifische Anwendungsfälle – spezifischere Tutorials zur Erledigung bestimmter Aufgaben.
• Begriffserklärungen/Nachschlagewerke – helfen Sie Benutzern, wichtige Begriffe 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 du dir die benutzerorientierteren Artikel von Gravity Forms ansiehst, wirst du viele Schritt-für-Schritt-Anleitungen sehen, wie du Aufgaben mit der Softwareoberfläche erledigst, zusammen mit Glossaren und Erklärungen wichtiger Funktionen.

Im Vergleich zur Entwickler-Software-Dokumentation siehst du 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 deine Software-Dokumentation auf deiner Website zu veröffentlichen, benötigst du ein spezielles Software-Dokumentations-Tool oder ein Wissensmanagementsystem.

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

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

Heroic Knowledge Base

Heroic Knowledge Base ist ein Plugin für Dokumentation und Wissensmanagement 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 weiterhin auf alle Funktionen zugreifen, die Sie für die Erstellung effektiver Software-Dokumentation 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, kannst du dein Setup auch nach Bedarf ändern.

Sie können sie ö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 Dokumentations-Tool, das darauf ausgerichtet ist, dir bei der Erstellung von Entwicklerdokumentationen zu helfen.

Wenn du dich speziell auf die Erstellung technischer Entwicklerdokumentationen konzentrierst, kann dies eine weitere gute Option sein, die du in Betracht ziehen kannst.

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 einen kostenpflichtigen Read the Docs for Business-Service, der bei 50 US-Dollar pro Monat beginnt.

GitBook

GitBook ist ein weiteres technisches Software-Dokumentationstool, mit dem Sie Ihre Dokumentation über Git verwalten können, mit Unterstützung für GitHub- und GitLab-Repositories.

Oder wenn du Git nicht verwenden möchtest, kannst du mit GitBook deine 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.

Entdecken: 15 beste Dokumentenmanagement-Software

Best Practices für die Erstellung von Software-Dokumentation

Um das Ganze abzurunden, lass uns einige Best Practices für Software-Dokumentation untersuchen, die dir helfen, effektive Dokumentation zu erstellen.

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

Wenn du einen Artikel für die Software-Dokumentation schreibst, 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-Beiträgen an und schreiben einen Artikel, der Social-Media-Managern hilft, ihren ersten Social-Media-Beitrag 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

Bei der Erstellung von Software-Dokumentationen ist es leicht, in die Falle zu tappen, mit der Dokumentation zu warten, bis ein Projekt abgeschlossen ist.

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

Um dies zu vermeiden, machen Sie die Software-Dokumentation zu einem bewussten Bestandteil des Softwareentwicklungszyklus. Wenn eine neue Funktion oder ein neues Produkt noch nicht dokumentiert ist, ist es 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 Menschen dabei zu helfen, effektiver mit Ihrer Software-Dokumentation zu arbeiten, ist es wichtig, dass Sie über alle Ihre Dokumentationen hinweg einheitliche Formatierung und 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, sollten Sie möglicherweise einen speziellen Styleguide für Software-Dokumentation 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 vordefinierte Callouts, um wichtige Informationen oder Warnungen hervorzuheben. Durch deren Verwendung können Sie eine konsistente Formatierung in Ihrer gesamten Dokumentation 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, werden Sie jedoch wahrscheinlich jemanden mit dem entsprechenden technischen Wissen beauftragen wollen, diese Dokumente zu schreiben.

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.

Entdecken: So schreiben Sie gute Dokumentationen – Der Leitfaden für Anfänger

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 sich darauf konzentrieren, die Auffindbarkeit Ihrer Software-Dokumentation zu verbessern.

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

Zum Beispiel möchten Sie in der Regel Ihre Endbenutzerdokumentation von der Software-Dokumentation für Entwickler 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 bieten eine integrierte Live-Suchfunktion, einschließlich Heroic Knowledge Base.

Entdecken: 5 beste WordPress-Suchfilter-Plugins

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 ist Ihre Dokumentation nicht nur „nicht hilfreich“, sondern könnte Ihre Benutzer tatsächlich verwirren.

Um sicherzustellen, dass diese Aktualisierungen erfolgen, sollten Sie bestimmte Personen für die Dokumentation und den Aktualisierungsprozess verantwortlich machen. Auf diese Weise gibt es keine Unklarheiten darüber, wer für die Richtigkeit 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 des Kundenfeedbacks zu automatisieren, sollten Sie nach einem Dokumentenmanagement-Tool suchen, das integrierte Funktionen für Kundenfeedback bietet.

Zum Beispiel können Benutzer mit dem Heroic Knowledge Base Plugin einen Artikel als hilfreich oder nicht hilfreich bewerten und optional auch Freitext-Feedback 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-Dokumentationen, 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 effektive Dokumentationen 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 die Kontrolle einer selbst gehosteten Plattform mit allen Funktionen und Möglichkeiten, die Sie benötigen, um hochwertige Software-Dokumentationen zu veröffentlichen.

Chris Hadley Gründer

Chris ist der Gründer von HeroThemes. Mit tiefen Wurzeln im WordPress-Ökosystem hat er über ein Jahrzehnt damit verbracht, Tools zu entwickeln, die Unternehmen helfen, einen besseren Kundensupport zu bieten – darunter Heroic KB und Heroic Inbox. Über den HeroThemes-Blog schreibt er über Wissensdatenbankstrategien, Self-Service-Support und wie Teams KI einsetzen können, um ihre Hilfeinhalte effektiver zu gestalten. Er hat eine Leidenschaft dafür, komplexe Support-Herausforderungen in einfache, elegante Lösungen zu verwandeln.

Vollständige Biografie anzeigen

E-Commerce WordPress SaaS Dokumentation Helpdesk-Software Kundenbetreuung