Softwaredokumentation ist eine Sammlung von Anleitungen und Artikeln, die Entwicklern/Benutzern helfen, Ihre Software zu verstehen. Sie umfasst eine Vielzahl verschiedener Dokumente von API-Dokumenten bis hin zu README-Dateien. Sie alle sind jedoch durch ein gemeinsames Ziel vereint.
Sie liefern Informationen über Software. Einige Dokumentationen helfen Endbenutzern, sich zu orientieren, Fehler zu beheben oder mit der Verwendung einer Software zu beginnen. Andere Dokumentationen liefern Entwicklern detaillierte technische Informationen über die Software.
Aber Sie haben bestimmt noch weitere Fragen, weshalb dieser Artikel Folgendes behandelt:
- Warum wird sie überhaupt benötigt?
- Wer verwendet sie?
- Wie wird sie erstellt?
- Welche Software soll man wählen?
- Unsere Lieblingsbeispiele für Softwaredokumentation
Was ist das Besondere an Softwaredokumentation?
Softwaredokumentation hilft Benutzern, mehr Wert aus Ihrer Software zu ziehen und darauf aufzubauen (wenn Sie eine API haben). Sie ist äußerst nützlich für Benutzer und Entwickler, aber aus unterschiedlichen Gründen:
Benutzer
- Klare Anweisungen und Erklärungen erleichtern die Verwendung der Software.
- Schneller Zugriff auf Informationen spart Zeit.
- Schritt-für-Schritt-Anleitungen und Tipps zur Fehlerbehebung reduzieren Frustration.
- Hilft ihnen, sich selbst zu helfen, anstatt Ihre CS-Bandbreite zu beanspruchen
- Hilft ihnen, neue/effizientere Möglichkeiten zur Nutzung Ihres Produkts zu entdecken
Entwickler
- Die Dokumentation beschleunigt die Entwicklung, indem sie Details zu APIs, Bibliotheken und Frameworks bereitstellt.
- Ein gemeinsames Verständnis des Designs und der Implementierung der Software verbessert die Zusammenarbeit.
- Anleitungen zu Best Practices und Codierungsstandards erhöhen die Codequalität.
Tatsächlich ist es laut The State of API report einer der wichtigsten Faktoren für Entwickler bei der Arbeit an APIs.
Wer verwendet Softwaredokumentation?
Softwaredokumentation wird von den Entwicklern und Endbenutzern der Software verwendet. Viele Leute nehmen an, dass technische Dokumente are only used by developers. In reality, end-users also look at your software documentation to look for specific features and use cases.
Nehmen wir zum Beispiel OpenAI.
Tausende von Autoren, Vermarktern und KI-Enthusiasten nutzen ihre Softwaredokumentation, um neue Anwendungsfälle zu erkunden und Best Practices zu erlernen.
Während die Dokumentation von OpenAI sowohl für Benutzer als auch für Entwickler gedacht ist, wird die meiste Softwaredokumentation in folgende Kategorien unterteilt:
- User-focused: This is written for anyone from customers to testers to external stakeholders.
- Entwicklerorientiert: Sie sind in der Regel technischer and referred to by developers.
Lassen Sie uns ihre Unterschiede im Detail verstehen:
Benutzerorientierte Softwaredokumentation
Benutzerorientierte Softwaredokumentation hilft Menschen, Ihre Software effektiv zu nutzen. Sie enthält Details zu Ihrer Software, zeigt ihnen, wie sie heruntergeladen und/oder eingerichtet wird, und behebt alle Probleme.
Beispiele
Einige gängige Beispiele für benutzerorientierte Softwaredokumentation sind:
- How-to- und Benutzerhandbücher
- Versionshinweise
- Tutorials
- Referenzdokumente
- Softwaredesign-Dokumente
- Erläuterungen (oft einschließlich Videos, Grafiken und Screenshots)
- Einrichtungs- und Fehlerbehebungsanleitungen
- Häufig gestellte Fragen
Entwicklerorientierte Softwaredokumentation
Entwicklerorientierte Dokumente sind in der Regel für Personen ohne Branchenerfahrung schwieriger zu verstehen, sollten aber dennoch so klar wie möglich geschrieben sein.
Beispiele
- Back-End-Versionshinweise
- Testpläne
- API-Dokumentation
- README-Dateien
- Produktanforderungsdokumente
- Systemdokumentation
- Quellcodedokument
- Andere technische Dokumentation & technische Spezifikationen
Wie können Sie ein Tool für Softwaredokumentation auswählen?
Sie sollten ein Tool für Softwaredokumentation basierend auf seinen Funktionen, seiner Benutzerfreundlichkeit und seinen Funktionen für die Zusammenarbeit auswählen.
Ein gutes Tool für Softwaredokumentation macht diese 3 Dinge wirklich gut:
- Verfügt über eine Versionskontrolle (damit die Leute auf die Dokumentation für ältere Versionen zugreifen können)
- Verfügt über einen einfachen Editor zum Hinzufügen von Bildern, Hyperlinks und Code-Snippets
- Verfügt über eine Suchfunktion
- Ist einfach hostbar, indexierbar und teilbar
- Verfügt über Funktionen für die Zusammenarbeit (Genehmigungs-Workflows für Dokumente, Kommentare usw.)
Es gibt natürlich noch weitere Funktionen, die von modernen Tools angeboten werden. Aber 90 % Ihrer Erfahrung hängen von den 5 oben aufgeführten Kernfunktionen ab.
Welche Software ist am besten für Softwaredokumentation geeignet?
Die besten Tools zum Schreiben von Softwaredokumentation sind Docusaurus, Swagger, ReadMe und Slite. Satteln wir auf und erkunden wir ein paar edle Optionen:
- Docusaurus: Built on React, it’s the king of snappy UIs. With Docusaurus, you can craft documentation websites that are as modern and engaging as a millennial's Instagram feed. Customize it to your heart's desire with themes and plugins, and watch your docs seamlessly integrate with your version control system. It's like a well-oiled machine, ready to showcase your code's magic.
- Swagger: Swagger ist der Rockstar. Sie können Ihre API-Endpunkte, Parameter und Antworten auf standardisierte Weise dokumentieren.
- ReadMe: ReadMe ist eine benutzerfreundliche Plattform, die das Erstellen und Veröffentlichen von Softwaredokumentation zum Kinderspiel macht. Mit Funktionen wie Versionskontrolle und Analysen können Sie Änderungen verfolgen und die Auswirkungen Ihrer Dokumentation messen.
- Slite: Slite ist eine ausgezeichnete Option zum Schreiben benutzerorientierter Softwaredokumentation, während die oben genannten 3 in entwicklerorientierten Anwendungsfällen hervorragend sind. Es verfügt über KI-Bearbeitungsfunktionen, eine Benutzeroberfläche, die einfacher ist als Notion (das stimmt wirklich!) und die Möglichkeit, sich mit Ihren anderen Apps wie Slack zu verbinden.
Unsere Top-Tipps zum Schreiben großartiger Softwaredokumentation
Diese Tipps helfen Ihnen sicherzustellen, dass Ihr Dokumentationsentwicklungsprozess reibungslos verläuft:
1. Stellen Sie technische Redakteure ein
Versuchen Sie zunächst, ein Teammitglied zu identifizieren, das sich hervorragend mit Dokumentation auskennt. Viele Leute machen den Fehler, die Softwaredokumentation einer beliebigen Person in ihrem Team zuzuweisen, unabhängig von ihren Schreib- oder technischen Fähigkeiten. Dies ist einer der Hauptgründe für verwirrende oder schlecht zusammengestellte Dokumentationen. Wenn es sich wie Ihr Team anhört, sollten Sie in Erwägung ziehen, einen technischen Redakteur einzustellen.
Technische Redakteure im Softwarebereich verfügen sowohl über Branchen-Know-how als auch über Schreiberfahrung. Sie werden sich auch kompliziert und dem Schreibprozess widmen. Einen einzustellen ist es wert.
2. Erstellen Sie einen Dokumentationsplan
Ein weiterer häufiger Fehler bei der Softwaredokumentation ist das Eintauchen, bevor Sie mit der Planung fertig sind. Bestehen Sie darauf, einen Überblick über alle verschiedenen Arten von Dokumentationen zu erstellen, an denen Sie und Ihr Team arbeiten werden. Dies hilft Ihnen, während des gesamten Entwicklungsprozesses organisiert zu bleiben und erleichtert es, die Arbeit an verschiedene Teams zu delegieren.
Dokumentationspläne tragen auch zu einer höheren Schreibqualität bei. Sie vermeiden die Wiederholung von Informationen und es ist für Ihre Leser einfacher, insgesamt zwischen Ihren Dokumenten zu navigieren.
3. Vergessen Sie nicht die Versionskontrolle
Die Softwaredokumentation sollte so oft wie Ihr Produkt aktualisiert werden. Um sicherzustellen, dass Ihre Dokumentation mit Ihren Produktaktualisierungen Schritt hält, wählen Sie ein Tool mit Versionskontrolle. (Die meisten von ihnen tun es)
Heutzutage verwenden viele Teams Design-Dokumentationsvorlagen that saves automatically and updates in real-time
4. Arbeiten Sie zusammen
Softwaredokumentation wird am besten in Zusammenarbeit geschrieben. Obwohl sie einen Eigentümer haben sollte, sollte Ihr gesamtes Projektteam auf die eine oder andere Weise zu Ihrer Dokumentation beitragen. Es hilft Ihnen, die Dinge viel schneller zu erledigen. Das Schreiben von Dokumentation ist arbeitsintensiv und wird mit mehr Mitwirkenden schneller abgeschlossen
5. Denken Sie an Ihr Publikum - Entwickler oder Kunden?
Der einfachste Weg, um zu priorisieren, welche Art von Dokumentation Sie zusammenstellen müssen, ist, über Ihr Publikum nachzudenken. Die Festlegung, ob Sie für Endbenutzer oder Programmierer und Ingenieure schreiben, hilft Ihnen von Anfang an, die Art von Dokumentation einzugrenzen, auf die Sie sich konzentrieren möchten.
6. Stellen Sie einen Styleguide zusammen
Styleguides können alles von Sprache und Schreibstil bis hin zu Formatierung und Schriftarten umfassen. Sie decken eine breite Palette von Elementen ab, darunter:
- Sprache: Styleguides legen das bevorzugte Vokabular, die Grammatik und die Verwendung für eine bestimmte Organisation oder Publikation fest. Dies umfasst Anleitungen zu Zeichensetzung, Großschreibung, Silbentrennung und Rechtschreibung.
- Schreibstil: Styleguides geben Anleitungen zum allgemeinen Ton und Stil des Schreibens, einschließlich der Verwendung von aktivem Sprachgebrauch, prägnanter Sprache und klarer Organisation. Sie können auch Richtlinien für bestimmte Arten des Schreibens enthalten, z. B. technisches Schreiben, Geschäftsschreiben und akademisches Schreiben.
- Formatierung: Styleguides geben Anleitungen zur Formatierung von Text, einschließlich der Verwendung von Überschriften, Unterüberschriften, Aufzählungszeichen und nummerierten Listen. Sie können auch Richtlinien für die Verwendung von Tabellen, Bildern und anderen visuellen Elementen enthalten.
- Schriftartauswahl: Styleguides legen die bevorzugten Schriftarten für die Verwendung in Überschriften, Textkörper und anderen Elementen fest. Sie können auch Anleitungen zur Verwendung verschiedener Schriftgrößen, -stärken und -farben geben.
- Zusätzliche Elemente: Zusätzlich zu diesen Kernelementen können Styleguides auch Anleitungen zu anderen Aspekten des Schreibens und Veröffentlichens enthalten, wie z. B.: etwas Text
- Zitate und Referenzen: Styleguides geben Anleitungen zur korrekten Zitierung von Quellen im Text und in einer Bibliographie.
- Berechtigungen und Urheberrecht: Styleguides geben Informationen darüber, wie man Berechtigungen zur Verwendung urheberrechtlich geschützten Materials erhält und wie man Quellen korrekt angibt.
- Rechtliche und ethische Überlegungen: Styleguides können Anleitungen zu rechtlichen und ethischen Überlegungen im Zusammenhang mit dem Schreiben und Veröffentlichen enthalten, wie z. B. Plagiat, Verleumdung und Datenschutz.
Styleguides sollten obligatorisch sein if multiple people are writing your documentation.
Fazit
Der Dokumentationsentwicklungsprozess mag anfangs überwältigend erscheinen, sollte aber eine Standardpraxis für Ihr Team sein. Stellen Sie Ihren Dokumentationsplan zusammen, gehen Sie die Dinge Schritt für Schritt an und Sie werden erstaunt sein, was Sie sich einfallen lassen.
Stöbern Sie in den Optionen, die wir zusammengestellt haben, um das Schreiben und Bearbeiten Ihrer Dokumentation einfach und angenehm zu gestalten, und greifen Sie auf unsere Tipps und Tricks zurück, wenn es um das Schreiben Ihrer Softwaredokumentation geht.
