Einführung

Stellen Sie sich vor, Sie haben ein Open-Source-Projekt entdeckt, das perfekt zu Ihren Interessen passt. Sie sind darauf erpicht, es zu nutzen oder dazu beizutragen, aber wo fangen Sie an? Die Antwort liegt in der Dokumentation des Projekts.

Denken Sie jetzt an Open Source Documentation als Leitfaden, um einem Benutzer zu helfen, das Beste aus einem Projekt herauszuholen. Es führt den Benutzer durch die Feinheiten des Projekts, hilft ihm aber auch, die Kernprinzipien des Projekts zu verstehen, wie man es verwendet und wie man seine Beiträge leistet.

In diesem Artikel werden wir uns mit der Open-Source-Dokumentation, den Arten von Open-Source-Dokumentationen, der Bedeutung, bewährten Verfahren für die Erstellung und schließlich Tools zur Optimierung des Prozesses der Erstellung einer Open-Source-Dokumentation befassen.

Was genau ist Open Source Documentation?

Zunächst einmal definieren wir „Open Source“. Open Source bedeutet in einfachen Worten eine Art von Software, deren Quellcode frei verfügbar ist, damit die Öffentlichkeit ihn überprüfen, ändern, verbessern und verteilen kann. Beispiele hierfür sind: das Linux-Betriebssystem, der Firefox-Webbrowser, MongoDB usw.

Jetzt bezieht sich Open Source Documentation auf schriftliche Materialien, die mit Open-Source-Software verbunden sind. Es bietet Informationen zur Verwendung, Funktionalität und Wartung der Produkte. Es enthält Details und Informationen zu den Funktionen der Software, der Installation, Konfiguration und Verwendung. Diese Dokumentation wird normalerweise der Öffentlichkeit zusammen mit dem Quellcode zur Verfügung gestellt.

Die Open-Source-Dokumentation dient als umfassende Ressource für Entwickler, Benutzer und Beitragende und bietet wesentliche Informationen über den Zweck, die Funktionen und die Verwendung des Projekts. Zu Beginn können Open-Source-Projekte überwältigend wirken, aber mit Hilfe einer guten Dokumentation können Benutzer und Beitragende das Projekt verstehen.

Arten von Open-Source-Dokumentationen

Open-Source-Projekte haben in der Regel 3 Arten von Dokumentationen. Jede davon erfüllt spezifische Anforderungen. Dazu gehören Technische Dokumentation, Produkt-Dokumentation und Richtlinien.

Technische Dokumentation : Diese Dokumentation richtet sich an Entwickler. Sie taucht tief in den Code ein, erklärt die API und zeigt, wie man die Programmierschnittstelle des Projekts verwendet. Sie umfasst auch Einführungsdokumente für das Projekt, Richtlinien für Entwickler, die mit dem Projekt arbeiten, und Anweisungen zur Konfiguration der Entwicklungsumgebung. Beispiele für technische Dokumentationen sind API-Dokumentationen, Entwicklerhandbücher und READMEs.

Produkt-Dokumentation : Diese Dokumentation richtet sich an die Benutzer des Projekts. Sie umfasst Benutzerhandbücher, Schnellstartanleitungen, Installationsanleitungen, Problembehandlungsanleitungen, FAQ usw. Sie konzentrieren sich im Wesentlichen auf die Benutzererfahrung und helfen den Benutzern dabei, die Projekte, ihre Funktionen und die Verwendung des Projekts zu verstehen.

Richtlinien : Diese Dokumentation ist auf die Beitragenden des Projekts zugeschnitten. Sie hilft den Beitragenden dabei, das Projekt zu navigieren. Die gängigen Arten von Open-Source-Projektrichtlinien sind:

Beitragsanleitungen : Sie sind wirklich wichtig, da sie erklären, wie man zum Projekt beitragen kann, einschließlich Code-Einreichungen und Fehlerberichten/ Fixes.
Styleguides: bieten Informationen zu bevorzugtem Stil, Formatierung und Benennungskonventionen. Es gewährleistet Qualität und Konsistenz im Code und bei den Beiträgen.
Verhaltenskodex : gibt das erwartete Verhalten von Beitragenden und Gemeindemitgliedern an.

Wichtigkeit der Open-Source-Dokumentation

Eine gute Dokumentation ist von größter Bedeutung, entweder für den Benutzer des Projekts oder für den Beitragenden zum Projekt. Schauen wir uns an, wie eine gute Dokumentation den Benutzern sowie den Beitragenden eines Open-Source-Projekts hilft.

Für Benutzer:

Verbesserte Benutzererfahrung : Eine gute Dokumentation hilft dem Benutzer zu verstehen, wie er das Projekt effektiv nutzen und das Beste daraus machen kann. Sie bietet eine schnellere Lösung für Probleme, mit denen ein Benutzer möglicherweise konfrontiert wird, wenn er das Projekt verwendet.
Einfachere Übernahme und Nutzung der Software: Eine klare und präzise Dokumentation erleichtert das Verständnis der Funktionen und der Funktionalität der Software. Sie verringert die Lernkurve und macht die Software für eine breitere Benutzergruppe zugänglicher.
Problembehebung: Eine ausführliche Dokumentation kann Benutzern bei der Fehlersuche und der eigenständigen Lösungsfindung helfen. Dies verringert die Abhängigkeit von Supportmitarbeitern und verbessert insgesamt die Benutzererfahrung.
Reduzierte Supportkosten: Eine gute Dokumentation kann die Anzahl der Supportanfragen minimieren und sowohl Benutzern als auch Entwicklern Zeit und Ressourcen sparen.

Für Mitwirkende:

Klareres Verständnis des Projekts : Um zu einem Projekt beizutragen, ist es notwendig, das Projekt zu verstehen. Eine gute Dokumentation hilft dem Leser, das Projekt zu verstehen und zu erfahren, wie er mit seinem Beitrag beginnen kann.
Effektives Onboarding : Eine gute Dokumentation erleichtert den Einstiegsprozess für die Mitwirkenden. Sie hilft ihnen, sich mit dem Code des Projekts, dem Ablauf und den erforderlichen Details vertrauter zu machen, die sie für ihre Beiträge benötigen.
Verbesserte Zusammenarbeit: Klare und präzise Dokumentation schafft eine gemeinsame Basis für Mitwirkende, um sicherzustellen, dass jeder die Ziele, Architektur und Kodierungsnormen des Projekts versteht. Mitwirkende können schnell die Informationen erhalten, die sie benötigen, um ihre Aufgaben durchzuführen, was Verzögerungen und Missverständnisse reduziert.

Best Practices zur Erstellung einer guten Dokumentation

Aus dem, was wir bisher besprochen haben, wird deutlich, dass das Schreiben einer guten Dokumentation für Ihr Open-Source-Projekt wirklich entscheidend ist. Um eine gute Dokumentation zu erreichen, die den Bedürfnissen Ihrer Benutzer und Mitwirkenden entspricht, sind hier einige Dinge, die Sie tun sollten.

Schreiben Sie klar und prägnant, damit Ihre Leser leicht verstehen, was Sie vermitteln möchten. Es ist wichtig, komplexe technische Fachbegriffe zu vermeiden, die Ihre Leser verwirren könnten, da der Sinn der Dokumentation darin besteht, die Benutzererfahrung zu verbessern.

Organisieren Sie Ihre Dokumentation strukturiert und nach einem klaren Muster. Dazu gehört, Ihre Informationen logisch mit Überschriften, Unterüberschriften und Aufzählungspunkten anzuordnen. Ihre Dokumentation sollte einem strukturierten Muster folgen, alles sollte gut von oben nach unten fließen und es sollte für die Leser einfach sein, zu folgen.
Schreiben Sie mit den Bedürfnissen der Benutzer im Hinterkopf. Es ist wichtig, sich in ihre Lage zu versetzen. Ihre Dokumentation sollte eine hilfreiche Ressource sein und kein Eintrittshindernis. Erklären Sie Konzepte so klar wie möglich; gehen Sie keine Annahmen ein. Sie können Code-Snippets einfügen, um spezifische Konzepte zu erläutern, häufige Fragen vorwegzunehmen und klare Lösungen/Antworten bereitzustellen.
Halten Sie Ihre Dokumentation aktuell, indem Sie sie aktualisieren, wann immer Änderungen am Projekt vorgenommen werden. Ihre Dokumentation sollte zusammen mit dem Code versendet werden; wenn die Code-Basis aktualisiert wird, sollte auch die Dokumentation aktualisiert werden.
Stellen Sie klare Anweisungen bereit, wie man zum Projekt beitragen kann. Auf diese Weise können Personen, die bereit sind, beizutragen, sich im Projekt zurechtfinden und ihre Änderungen leicht vornehmen.
Überprüfen Sie Fehler, Inkonsistenzen oder veraltete Informationen. Bitten Sie auch um Feedback von Ihren Benutzern, das hilft bei der Verbesserung der Dokumentation.
Zu guter Letzt sollte man sich auf Tools stützen, die helfen, eine gute Dokumentation zu erreichen. Es gibt viele Tools, die Sie verwenden können, um

Tools zur Erstellung einer guten Dokumentation

Wie bereits erwähnt, gibt es viele Tools, die Sie nutzen können, um eine gute Dokumentation zu erstellen, die Benutzer leicht durchsehen und verstehen können. Hier sind einige davon.

Sphinx : ein beliebtes Tool zur Erstellung technischer Dokumentation, insbesondere für Python-Projekte. Es unterstützt verschiedene Ausgabeformate (HTML, PDF, LaTeX) und verfügt über ein reichhaltiges Ökosystem von Erweiterungen.
Doxygen : ein Werkzeug zur Erstellung von API-Dokumentationen aus Quellcode-Kommentaren. Es unterstützt verschiedene Programmiersprachen und kann Dokumentationen in HTML, LaTeX und anderen Formaten erzeugen.
MkDocs: ein einfacher, schneller und konfigurierbarer Dokumentationsgenerator, der Markdown zum Schreiben von Inhalten verwendet. Er eignet sich gut für kleinere Projekte.
Read the Docs: eine Hosting-Plattform für Dokumentationen, die mit Sphinx oder MkDocs erstellt wurden. Sie vereinfacht die Softwaredokumentation durch das Erstellen, Versionieren und Hosten Ihrer Dokumente.
Git: Git ermöglicht es Ihnen, Änderungen an Ihrer Dokumentation im Laufe der Zeit nachzuverfolgen. Dadurch können Sie problemlos zu früheren Versionen zurückkehren, wenn nötig, und es hilft auch, versehentliche Löschungen zu vermeiden. Es unterstützt kontinuierliche Aktualisierungen der Dokumentation.

Sie können sich die Dokumentationen jedes Tools genau ansehen, um ein tiefgreifendes Verständnis dafür zu erhalten, wie sie funktionieren und wie Sie mit ihrer Nutzung beginnen können.

Abschluss

Zusammenfassend lässt sich sagen, dass eine gute Dokumentation darüber entscheidet, wie gut ein Projekt verstanden und genutzt wird. Es ist unerlässlich, eine klare und präzise Dokumentation zu haben, die den Bedürfnissen aller gerecht wird, die ein Open-Source-Projekt nutzen möchten.

Aus dem Artikel geht hervor, dass Sie durch Investition von Zeit und Mühe in die Erstellung einer gründlichen, gut strukturierten und zugänglichen Dokumentation nicht nur die Benutzererfahrung verbessern, sondern auch die Nachhaltigkeit Ihres Projekts sicherstellen.

Das nächste Mal, wenn Sie auf ein Open Source-Projekt stoßen, das Ihre Aufmerksamkeit erregt, scheuen Sie sich nicht, tiefer einzutauchen; die Dokumentation wird Ihr Leitfaden sein, um das Projekt zu nutzen oder dazu beizutragen.

Ressourcen

https://opensource.googleblog.com/2018/10/building-great-open-source-documentation.html

https://opensource.com/article/20/3/documentation

https://herothemes.com/blog/best-documentation-tools/