So schreiben Sie eine gute Dokumentation für Ihre Open-Source-Bibliothek

Wenn Sie in die Steinzeit schauen (sprich: vor zehn Jahren), werden Sie feststellen, dass es vielen Bibliotheken, vielleicht abgesehen von den am häufigsten verwendeten, an guter oder gar keiner Dokumentation mangelte. Entwickler erwarteten oft, dass ein paar Codebeispiele ausreichen würden, damit ein Neuling verstehen würde, was sie sich vorgestellt hatten und wie sie ihre Arbeit verwenden sollten.

Das Wachstum von Open Source erforderte jedoch, dass die Dokumentation immer mehr geschrieben wurde. mit Blick auf den Endverbraucher. Unternehmen haben erkannt, dass die Präsenz in der Open-Source-Welt ein wertvolles Kapital ist, um neue Kunden und neue Entwickler zu gewinnen. Open-Source-Projekte schaffen Glaubwürdigkeit und bauen einen guten Ruf auf. Daher wurde der Anreiz, solide Dokumente zu schreiben, immer wichtiger.

Ein weiterer Grund, den ich in erster Linie auf das Wachstum von Node als beliebte Technologie zurückführen würde, sind konkurrierende Bibliotheken innerhalb von Ökosystemen — eine Situation, die vor dem Aufkommen von npm selten zu beobachten war. In Python zum Beispiel gibt es normalerweise eine Möglichkeit, eine Sache zu tun. In JavaScript gab es vor Node auch nicht viele Bibliotheken, um eine Sache auf unterschiedliche Weise zu erledigen — denken Sie nur an beliebte Alternativen zu jQuery.

Heutzutage können wir jedoch unseren Technologie-Stack selbst auswählen, und die Entwickler dieser Bibliotheken und Frameworks geben sich große Mühe, sie zu erlernen und zu verwenden schmerzlos und schnell wie möglich. JavaScript-Entwickler kann zwischen Angular, React, Vue und vielen anderen, weniger beliebten Frameworks am Frontend und Express, Koa oder Sails im Backend wählen, zusätzlich zu einer Million anderer Bibliotheken dazwischen.

Bestandteile einer guten Dokumentation

Eine Dokumentation besteht aus vielen Teilen, unter anderem:

• Lies mich
• Referenz
• Ratgeber
• Kochbuch
• Blogbeitrag

Jedes davon erfüllt unterschiedliche Zwecke, und die Grenze zwischen den Arten von Dokumenten ist manchmal verschwommen.

Lies mich

Die Readme-Datei ist oft der erste Kontakt, den potenzielle Benutzer mit Ihrem Produkt herstellen. Es kann als eine Art Kombination der anderen Dokumenttypen betrachtet werden, unterscheidet sich aber in gewisser Weise von allen anderen. Mit Readme verkaufen Sie Ihre Open-Source-Bibliothek. Beachten Sie jedoch, dass Sie sich kurz und informativ fassen sollten.

Beschreiben Sie zunächst, womit Ihre Bibliothek Ihren Benutzern hilft, und welche ihrer Probleme löst es. Sie können versuchen, Beispiele für häufige Anwendungsfälle zu nennen. Ein gut geschriebener erster Absatz ist ein guter Anfang für jede Readme-Datei. Wenn Ihre Readme-Datei länger als eineinhalb Seiten ist, empfiehlt es sich, ein Inhaltsverzeichnis beizufügen.

Quelle des Bilds

Listen Sie die Voraussetzungen und Abhängigkeiten auf, die der Benutzer haben sollte, und beschreiben Sie den Installationsvorgang. Zeigen Sie ein einfaches Codebeispiel, noch besser, wenn es sich um einen echten Anwendungsfall handelt, und verlinken Sie auf eine detailliertere Dokumentation.

Fügen Sie abschließend eine Lizenz hinzu und listen Sie die Mitwirkenden auf. Du kannst auch einen Absatz hinzufügen, in dem erklärt wird, wie du zu deiner Bibliothek beitragen kannst. Denken Sie daran, dass Open Source auf Respekt vor der Zeit des anderen basiert. Wenn Ihre potenziellen Mitwirkenden sich darüber informieren können, wie Sie Ihre Bibliothek zum Laufen bringen können, ist jeder ein Gewinner.

Referenz

Eine Referenz ist vielleicht das technischste Dokument Ihrer Dokumentation. Ihr Zweck ist alle Funktionen auflisten Ihre Bibliothek enthüllt; ihre erwarteten Inputs, Outputs und Nebenwirkungen; Zweck und Implementierungsbeispiele. Die Beispiele in der Referenz sollten so isoliert und in sich geschlossen wie möglich sein.

Eine Referenz wird oft automatisch generiert, und es gibt mehrere Lösungen, um die Arbeit mit ihr und ihre Aktualisierung zu vereinfachen. Sie sollten jedoch bedenken, dass eine Referenz, die ausschließlich computergeneriert ist, für Ihre Benutzer schwer zu verstehen sein kann. Sie sollten sich bemühen, mindestens einen Satz Ihrer eigenen schriftlichen Erklärung pro Punkt in die Referenz aufzunehmen.

Außerdem kann es für bestimmte Entwickler hilfreich sein, genau zu verstehen, wie eine bestimmte Funktion implementiert wird. Ein nettes Feature, wenn auch sicherlich kein Muss, ist ein direkter Link zur Funktionsimplementierung im Code Ihrer Bibliothek.

Ratgeber

Ein Leitfaden ist im Wesentlichen ein Tutorial, das Ihrem Benutzer hilft durch alle Funktionen navigieren deiner Bibliothek. Bei großen, allgemeingültigen, eigensinnigen Frameworks ist der Leitfaden möglicherweise das umfangreichste Dokument der Dokumentation.

Beginnen Sie Ihren Leitfaden, indem Sie dessen Umfang skizzieren und festlegen, über welche Vorkenntnisse der Benutzer verfügen sollte. Wenn Sie beispielsweise eine Bibliothek schreiben, die bei der Verwaltung von HTTP-Anfragen hilft, wird erwartet, dass der Benutzer mit den grundlegenden Konzepten des Themas zumindest ein wenig vertraut ist.

Fangen Sie am Anfang an — behandeln Sie zuerst die grundlegendsten Themen und gehen Sie schrittweise zu komplizierteren Themen über. Ein guter Ausgangspunkt sind immer die Installationsprozesse für verschiedene Systeme. Es kann nützlich sein, sich eine Gruppe von Personen vorzustellen, die vor Ihnen sitzen und denen Sie Ihr Produkt erklären möchten. Denken Sie daran, dass es in diesem Fall respektvoller ist, Ihren Nutzern zu viel zu erklären, als wichtige Konzepte unklar zu lassen.

Fügen Sie gegebenenfalls Bilder und Diagramme sowie Codebeispiele hinzu. Möglicherweise möchten Sie den Code in Ihrer Dokumentation so vollständig wie möglich gestalten, damit der Benutzer bestimmte Teile einfach kopieren und einfügen kann. Er sollte jedoch logisch aufgeteilt und mit Kommentaren und Anmerkungen zu allgemeinen Anwendungen der im Code beispielhaften Funktionen durchsetzt sein.

Denken Sie daran, auch Ihren Guide zu testen. Wenn der Benutzer jedes Codebeispiel im Handbuch kopiert und einfügt, muss es funktionieren. Ich kann nicht genug betonen, wie frustrierend es für den Benutzer ist, wenn Codebeispiele aus den Dokumenten nicht funktionieren.

Kochbuch

Bei großen Allzweckbibliotheken ist das Kochbuch eine Sammlung detaillierter Lösungen für häufig auftretende Probleme, mit denen Ihre Benutzer bei der Verwendung Ihrer Bibliothek konfrontiert sein können. Im Gegensatz zum Leitfaden, der auf früheren Konzepten aufbaut, sollte jedes Rezept im Kochbuch in sich abgeschlossen sein. Außerdem können und sollten die Anwendungen von Funktionen, die zur Lösung eines Problems erforderlich sind, ausführlicher erklärt werden als in der Anleitung.

Kochbücher sind bei kleinen und fokussierten Bibliotheken nicht erforderlich und sollten nur in Betracht gezogen werden, wenn Konzepte besprochen werden, die eine größere Komplexität erfordern, als Sie vernünftigerweise in den Leitfaden aufnehmen könnten. Daher kann das Kochbuch als Sammlung von kurzen Tutorials darüber, wie ein gewünschtes Ergebnis erzielt werden kann.

Obwohl sich der Leitfaden in erster Linie auf Ihre eigene Bibliothek konzentrieren sollte, werden im Kochbuch Rezepte empfohlen, auf andere Dokumente zu verweisen und die Integration mit anderen Bibliotheken aufzuzeigen. Außerdem kannst du erklären, warum du einige Sprachfunktionen anderen vorziehst. Das hilft Ihrem Benutzer, nicht nur Ihre Bibliothek, sondern auch die Programmiersprache im Allgemeinen besser zu beherrschen.

Schließlich können Sie Beispiele hinzufügen, in denen Sie bestimmte Lösungen nicht verwenden oder falsche Codebeispiele oder Anti-Patterns angeben sollten. Denken Sie jedoch daran, sie deutlich von den richtigen Beispielen zu unterscheiden.

Blogbeitrag

Ein Blogbeitrag ist zwar nicht unbedingt Teil der Dokumentation, aber dennoch eine wichtige Information, die Ihre Benutzer schätzen können. Während sich die anderen Teile der Dokumentation darauf konzentrieren, wie Sie Ihre Bibliothek auf relevante Anwendungsfälle anwenden können, sollte Ihr Blogbeitrag erklären, warum das überhaupt erforderlich war.

Quelle des Bilds

Der Sinn eines Blogposts besteht darin, mit Ihren Benutzern in Kontakt zu treten und ihnen zu sagen, warum Ihre Lösung besser ist als andere. Sie können über das Problem schreiben, das Sie dazu inspiriert hat, die Bibliothek zu schreiben, oder die Gründe für ihre Existenz aufzeigen.

Beachten Sie, dass Sie trotz des Namens keinen Blog benötigen, um einen Blogbeitrag zu schreiben: Sie können dies in einem GitHub Gist tun und in der Readme-Datei darauf verlinken.

Vor der Veröffentlichung

Das Korrekturlesen der Dokumentation ist wichtig — das Lesen von Dokumenten mit schlechter Grammatik und Zeichensetzung wird schnell anstrengend. Überlegen Sie Weitergabe Ihrer Dokumente an einen Muttersprachler oder jemand, der Erfahrung mit Englisch hat und Ihnen mit der Sprache helfen kann. Wenn du diese Option nicht hast, lass deine Mitwirkenden Pull-Requests an deine Dokumente senden und fordere das sogar ausdrücklich in der Readme-Datei an. Es stehen dir auch eine Reihe automatisierter Tools zur Verfügung, die dir dabei helfen, wie zum Beispiel Grammatik oder Hemingway.

Ich werde auch wiederholen, dass Sie vor der Veröffentlichung Ihrer Dokumente überprüfen sollten, ob alle Ihre Codebeispiele funktionieren.

Fazit

In der heutigen Zeit sich ständig ändernder Entwicklungstrends ist Dokumentation wichtiger denn je. Es kann ein wichtiger Faktor sein, wenn es darum geht, die Präsenz Ihres Projekts in der Open-Source-Welt zu stärken, wenn es darum geht, Ihre Benutzer mit der Nutzung Ihrer Bibliothek vertraut zu machen und sie beim Erlernen der Bibliothek zu unterstützen.

Und außerdem ist das Schreiben von Dokumenten nicht so schlecht!