Was ist Softwaredokumentation? 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 eine qualitativ hochwertige Softwaredokumentation erstellen.

Aber was ist Softwaredokumentation eigentlich und wie können Sie sie für Ihr Projekt erstellen?

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

• Was ist Softwaredokumentation?
• Die verschiedenen Arten der Softwaredokumentation (mit Beispielen)
• So veröffentlichen Sie Ihre Softwaredokumentation (die besten Tools)
• Einige Best Practices für die Erstellung hochwertiger Softwaredokumentation

Lasst uns eintauchen!

Was ist Softwaredokumentation?

Bei der Softwaredokumentation handelt es sich um Inhalte, die Endbenutzern, Entwicklern und/oder Ihren Mitarbeitern helfen, Ihre Software zu verstehen und sie zur effektiven Erreichung ihrer Ziele zu nutzen.

Normalerweise veröffentlichen Sie die Softwaredokumentation auf Ihrer Website. Die Leute können dann darauf zugreifen, um mehr über Ihre Software und ihre Funktionsweise zu erfahren.

Innerhalb dieser weit gefassten Definition von Softwaredokumentation gibt es verschiedene Arten von Softwaredokumentation. Lassen Sie uns das als nächstes besprechen.

Die verschiedenen Arten der Softwaredokumentation

Sie können die verschiedenen Arten der Softwaredokumentation grob in einige große Kategorien einteilen.

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

• Benutzerdokumentation – Dies ist eine Dokumentation, die Sie für den Endbenutzer des Produkts erstellt haben. Es hilft ihnen zu verstehen, wie Sie Ihre Software aus der Perspektive eines normalen Benutzers verwenden, der möglicherweise über spezielle technische Kenntnisse verfügt oder nicht.
• Entwicklerdokumentation – hierbei handelt es sich eher um eine technische Softwaredokumentation, die Sie für Entwickler erstellt haben, beispielsweise eine API-Dokumentation.

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

• Externe Softwaredokumentation – Dies ist eine öffentlich zugängliche Dokumentation, die Sie erstellt haben, um Ihren Benutzern zu helfen.
• Interne Softwaredokumentation – dabei handelt es sich um eine private Dokumentation, die Sie für Ihre Mitarbeiter erstellt haben, um ihnen zu helfen, effektiver zu arbeiten und wichtige Details zu verstehen.

Beispielsweise verfügen Sie möglicherweise über einen Satz Entwicklerdokumentation für Ihre internen Teams, um die Arbeit an der Software zu unterstützen, und über einen anderen Satz öffentlich zugänglicher Entwicklerdokumentation für externe Entwickler.

Lassen Sie uns diese Arten von Softwaredokumentationen etwas detaillierter aufschlüsseln …

Beispiele für Softwaredokumentation für Entwicklerdokumentation

• API-Dokumentation – zeigen Sie Entwicklern, wie sie mit der API Ihrer Software interagieren.
• Readme – stellen Sie Ihre Software vor und erklären Sie, was sie tut – normalerweise das Erste, was die Leute lesen.
• Versionshinweise – Dokumentieren Sie neue Versionen Ihrer Software, einschließlich aller wichtigen Änderungen.
• Architekturdokumentation – zeigen Sie die Struktur Ihrer Software, möglicherweise einschließlich Diagrammen.
• Datenmodelldokumentation – Dokumentieren Sie 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.

Ein echtes Softwaredokumentationsbeispiel für entwicklerorientierte Dokumente finden Sie in der „Entwickler“-Dokumentation von Gravity Forms, die verschiedene Themen abdeckt, wie zum Beispiel:

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

So sieht beispielsweise die REST-API-Dokumentation aus:

Beispiele für Softwaredokumentationen für die Benutzerdokumentation

• Leitfaden „Erste Schritte“ – zeigen Sie Benutzern, wie sie Ihre Software schnell in Betrieb nehmen können.
• Tutorials für bestimmte Anwendungsfälle – spezifischere Tutorials zur Erledigung spezifischer Aufgaben.
• Begriffsglossare/Referenzhandbücher – helfen Benutzern, wichtige Begriffe und Details zu verstehen.
• FAQs – Beantworten Sie häufig gestellte Fragen.

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

Wenn Sie sich die eher benutzerorientierten Artikel von Gravity Forms ansehen, finden Sie zahlreiche Schritt-für-Schritt-Anleitungen zur Erledigung von Aufgaben mithilfe der Softwareschnittstelle sowie Glossare und Erläuterungen zu den wichtigsten Funktionen.

Im Vergleich zur Entwicklersoftwaredokumentation sehen Sie mehr Screenshots und Erklärungen in einfacher Sprache sowie viel weniger Codeblöcke.

So veröffentlichen Sie Softwaredokumentation: Drei beste Softwaredokumentationstools

Um Ihre Softwaredokumentation auf Ihrer Website zu veröffentlichen, benötigen Sie ein spezielles Softwaredokumentationstool oder eine Art Wissensmanagementsystem.

In diesem Abschnitt gehen wir kurz auf einige der besten Tools zur Softwaredokumentation ein. Im nächsten Abschnitt gehen wir dann auf einige Best Practices für die Erstellung hochwertiger Dokumentation ein.

Wenn Sie hier einen tieferen Einblick wünschen, lesen Sie vielleicht unsere vollständigen Leitfäden zu den besten Dokumentationstools und der besten technischen Dokumentationssoftware.

Heroische Wissensdatenbank

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

Mit der Heroic Knowledge Base können Sie Ihre Dokumentation selbst hosten und die volle Kontrolle behalten, während Sie gleichzeitig auf alle Funktionen zugreifen, die Sie zum Erstellen effektiver Softwaredokumentation benötigen.

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

• Flexibler Inhaltseditor , einschließlich integrierter Blöcke für Beschriftungen und andere wichtige Stildetails.
• Automatisches Inhaltsverzeichnis , damit Benutzer schnell erkennen können, welche Inhalte in einem Dokumentationsartikel behandelt werden, und zu bestimmten Abschnitten springen können.
• Revisionskontrolle und Versionsverlauf über das native WordPress-Revisionssystem.
• Inhaltserkennungsfunktionen , einschließlich Echtzeit-Ajax-Suche mit Live-Vorschlägen, Kategorien und mehr.
• Benutzer-Feedback-System , mit dem Benutzer Artikel als hilfreich oder nicht hilfreich bewerten und Feedback geben können.
• Suchanalysen, damit Sie sehen können, wonach Benutzer suchen, sowie alle Suchbegriffe, die keine Ergebnisse liefern.
• Widget für sofortige Antworten , mit dem Benutzer von überall auf Ihrer Website nach Softwaredokumentationen suchen und darauf zugreifen können.

Da Heroic Knowledge Base und WordPress beide selbst gehostet und Open Source sind, steht es Ihnen auch frei, Ihr Setup nach Bedarf zu ändern.

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

Heroic Knowledge Base beginnt bei nur 149 $ pro Jahr.

Lesen Sie die Dokumente

Read the Docs ist ein Dokumentationstool, das Sie bei der Erstellung von Entwicklerdokumentationen unterstützen soll.

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

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

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

• Integrierte Analysen, um zu sehen, was Ihre Benutzer lesen und suchen.
• Unterstützt mehrere gleichzeitige Builds , was hilfreich sein kann, wenn Sie mehrere Versionen Ihrer Software anbieten – z. B. einen Dokumentationssatz für Version 1.0 und einen anderen für Version 2.0.
• Exportieren Sie Dokumentation in verschiedene Formate, einschließlich PDF, HTML und Epub.
• Live- Suchvorschläge, um Benutzern das Auffinden von Dokumenten zu erleichtern.

Die Nutzung von 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-Dienst, der bei 50 US-Dollar pro Monat beginnt.

GitBook

GitBook ist ein weiteres technisches Softwaredokumentationstool, mit dem Sie Ihre Dokumentation mit Git verwalten können und sowohl GitHub- als auch GitLab-Repositorys unterstützen.

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-Teambearbeitung , 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, damit Benutzer Ihre Dokumentation einfach als PDF-Download exportieren können.

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

Für kommerzielle Softwareprojekte beginnt GitBook bei 8 $ pro Benutzer und Monat, bei mindestens 5 Benutzern. Das bedeutet, dass die günstigste monatliche Rate 40 $ pro Monat beträgt.

Best Practices für die Erstellung von Softwaredokumentationen

Lassen Sie uns zum Abschluss noch einen Blick auf einige Best Practices für die Softwaredokumentation werfen, die Ihnen bei der Erstellung einer effektiven Dokumentation helfen.

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

Wenn Sie einen Artikel zur Softwaredokumentation schreiben, ist es wichtig, zunächst einige grundlegende Fragen zu beantworten:

• Für wen schreiben Sie?
• Was möchte der Benutzer erreichen?
• Über welches technische Wissen verfügt der Anwender?

Wenn Sie die Antworten auf diese Fragen kennen, können Sie besser verstehen, welche Inhalte behandelt werden müssen und wie Sie den Artikel optimal strukturieren.

Nehmen wir zum Beispiel an, Sie bieten Social-Media-Planungssoftware an und schreiben einen Artikel, der Social-Media-Managern dabei hilft, ihren ersten Social-Media-Beitrag zu planen.

Wenn Sie Ihre Softwaredokumentation schreiben, sollten Sie sich darauf konzentrieren, einem normalen Endbenutzer den einfachsten Weg aufzuzeigen, wie er dieses Ziel erreichen kann.

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

Beziehen Sie die Softwaredokumentation in den Entwicklungsprozess ein

Wenn Sie eine Softwaredokumentation erstellen, tappen Sie leicht in die Falle und warten, 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 diese dokumentiert wurden.

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

Indem Sie die Dokumentation zu einer Kernanforderung des Softwareentwicklungsprozesses machen, können Sie sicherstellen, dass alles, was Sie versenden, von einer ordnungsgemäßen Dokumentation begleitet wird.

Verwenden Sie eine einheitliche Formatierung und einen einheitlichen Stil

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

Durch die Verwendung derselben Formatierung erfahren die Leser, wie Ihre Softwaredokumentation strukturiert ist, und können so schneller auf die benötigten Informationen zugreifen.

Um diese Konsistenz zu erreichen, möchten Sie möglicherweise einen speziellen Styleguide für die Softwaredokumentation erstellen.

Ihr Tool zur Verwaltung der Softwaredokumentation enthält möglicherweise auch Funktionen, die Ihnen dabei helfen, ein einheitliches Design zu erreichen.

Das Heroic Knowledge Base-Plugin enthält beispielsweise vorgefertigte Beschriftungen, um wichtige Informationen oder Warnungen hervorzuheben. Durch deren Verwendung können Sie eine einheitliche Formatierung in Ihrer gesamten Dokumentation sicherstellen.

Nutzen Sie Experten zum Schreiben technischer Dokumentation

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

Bei eher technischer Softwaredokumentation, beispielsweise einer entwicklerorientierten API-Dokumentation, möchten Sie jedoch wahrscheinlich jemanden mit den entsprechenden technischen Kenntnissen damit beauftragen, diese Dokumente zu schreiben.

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

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

Machen Sie es den Menschen leicht, Inhalte zu entdecken (Suche/Filter)

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

Um dieses Problem zu vermeiden, sollten Sie sich auf die Verbesserung der Auffindbarkeit Ihrer Softwaredokumentation konzentrieren.

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

Beispielsweise möchten Sie in der Regel Ihre Endbenutzerdokumentation von der Dokumentation der Entwicklersoftware 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.

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

Eine weitere nützliche Auffindbarkeitsfunktion sind Live-Suchvorschläge. Benutzer können mit der Eingabe einer relevanten Suchanfrage in das Suchfeld beginnen und sehen sofort Dokumentationsartikel, die dieser Suchanfrage entsprechen.

Viele Dokumentationstools verfügen über eine integrierte Live-Suchfunktion, einschließlich der Heroic Knowledge Base.

Halten Sie Ihre Softwaredokumentation auf dem neuesten Stand

Da sich Ihre Software ständig ändert, ist Ihre Softwaredokumentation immer in Arbeit.

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 bei Ihren Benutzern tatsächlich Verwirrung stiften.

Um sicherzustellen, dass diese Aktualisierungen durchgeführt werden, sollten Sie bestimmten Personen die Verantwortung für die Dokumentation und den Aktualisierungsprozess zuweisen. Auf diese Weise besteht keine Unklarheit darüber, wer dafür verantwortlich ist, dass alles korrekt bleibt.

Nutzen Sie Kundenfeedback, um Ihre Dokumentation zu verbessern

Sie sollten nicht nur Ihr eigenes Team mit der Überprüfung und Aktualisierung Ihrer Softwaredokumentation beauftragen, sondern auch Kundenfeedback berücksichtigen.

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

Um den Kundenfeedbackprozess zu automatisieren, sollten Sie nach einem Dokumentationsverwaltungstool suchen, das integrierte Funktionen für Kundenfeedback enthält.

Mit dem Heroic Knowledge Base-Plugin können Benutzer beispielsweise einen Artikel als hilfreich oder nicht hilfreich bewerten und optional auch Feedback in freier Form abgeben.

Anschließend können Sie alle diese Informationen in Ihrem Dashboard anzeigen, um schnell Dokumentationsartikel zu erkennen, die Sie verbessern müssen.

Beginnen Sie noch heute mit der Dokumentation Ihrer Software

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

Es gibt verschiedene Arten von Softwaredokumentation. Sie sollten daher darüber nachdenken, welche Arten den Anforderungen Ihres Softwareprojekts entsprechen.

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

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

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

Sie erhalten die Flexibilität und Eigenverantwortung einer selbst gehosteten Plattform mit allen Features und Funktionen, die Sie zum Veröffentlichen hochwertiger Softwaredokumentation benötigen.

Wenn Sie mehr erfahren möchten, klicken Sie hier, um zur Heroic Knowledge Base zu gelangen.