Ich bin der Schöpfer eines wachsenden Open Source-Projekts. Gegenwärtig bin ich ziemlich verzweifelt, wenn ich versuche, herauszufinden, wie die Dokumentation am besten verwaltet werden kann. Hier sind die Optionen, die ich in Betracht gezogen habe:
- HTML-Website
- Ein Github Wiki
- Auf Github gehostete Markdown-Dateien
- Alle Dokumente in Github README.md ablegen
Die Dokumentation ist bereits in Markdown geschrieben, ich kann nur nicht herausfinden, wie ich sie verfügbar machen möchte. Ich bin sehr angetan von Git, da ich die Dokumentation genauso verzweigen und markieren kann wie die Quelle.
Ich könnte eine Markdown-Bibliothek verwenden, um den Markdown in HTML zu übersetzen und auf einer gestalteten Website anzuzeigen. Ich müsste bei jeder Änderung Änderungen auf die Website hochladen, und es wäre schwierig, alle verschiedenen "Tags" der Dokumentation zu verwalten.
Github Wikis ändern sich (soweit ich weiß) nicht entsprechend der Branche, in der Sie sich befinden. Daher konnte ich zu einem bestimmten Zeitpunkt nur die "Master" -Version der Dokumentation im Github-Wiki-Formular haben.
Alles in die Github-README zu schreiben, ist ein bisschen ordentlich. Ich bekomme Verzweigungen und Markierungen, aber die Verwendung ist etwas anstrengend und eignet sich nicht gut für eine einfache Navigation.
Vermisse ich eine großartige Lösung? Welche anderen Optionen habe ich?
quelle
Antworten:
Eine Sache, die ich sagen würde, ist, dass sich die Dokumentation in den Quellcodedateien befinden MUSS (mit dem von Ihnen gewünschten Markup) und die daraus automatisch generierten Dokumente.
Zumindest auf Ihrer Site können Sie formatierte Downloads der Dokumente als Teil des Quellpakets generieren, sodass der Benutzer kein bestimmtes Dokumententool benötigt
Die Wahrscheinlichkeit, dass eine andere Person eine Funktion repariert / hinzufügt und dann ein Stück Markierungsdokumentation bearbeitet / hinzufügt, das in derselben Datei unmittelbar benachbart ist, ist gering, ABER die Wahrscheinlichkeit, dass sie in einem anderen Dokumentenspeicher eine völlig andere Datei findet, um dasselbe zu tun, ist gering weniger als Null.
Sie können jederzeit ein Tutorial.h haben, das große Textblöcke enthält, wenn Sie möchten - aber behandeln Sie es als Teil der Quelle
quelle
Wenn es sich bei Ihrem Projekt um eine Bibliothek handelt, gibt es nichts Schöneres als eine Dokumentation im Javadoc-Stil, um die API-Syntax anhand von Kommentaren im Code selbst zu dokumentieren.
In Bezug auf die Dokumentation zu Tutorials, Anwendungsbeispielen usw. empfehle ich dringend, ein Wiki-Format zu verwenden. Andere Projekte, die ich gesehen habe, haben separate Seiten für verschiedene Branchen. Wenn Sie eine neue Verzweigung starten, kopieren Sie einfach die nicht geänderten Elemente auf eine neue Seite und aktualisieren sie von dort aus.
Mein Grund, ein Wiki zu empfehlen, ist ungewöhnlich, aber aus persönlicher Erfahrung. Ich habe bei mehreren Gelegenheiten Dokumentationsaktualisierungen für Open Source-Projekte beigesteuert, aber alle waren in Wikis. Wenn ich etwas herauszufinden versuche und die Dokumentation irreführend oder nicht hilfreich ist, aktualisiere ich das Wiki, während ich in den Dokumenten bin und es in meinem Kopf frisch ist, nachdem ich es herausgefunden habe. Wenn auch nicht aus dem Gefühl heraus, etwas zurückzugeben, zumindest, weil ich weiß, dass ich es in ein oder zwei Jahren wahrscheinlich selbst noch einmal nachschlagen muss.
Wenn es kein Wiki gibt, ist die Eintrittsbarriere einfach zu hoch, um sich darum zu kümmern, wie die Dokumentation erstellt, wo sie gespeichert wird, die neuesten Informationen aus der Quellcodeverwaltung abgerufen, wie Änderungen vorgenommen und die eigentlichen Änderungen vorgenommen werden Durchsuchen der Mailinglisten, um einen Patch zu erhalten.
Wenn Sie eine strenge Kontrolle über Ihre Dokumentation wünschen, sollten Sie auf jeden Fall das verwenden, was für Sie am bequemsten ist, da Sie meistens die einzige Person sind, die diese aktualisiert. Wenn Sie die Beteiligung der Community fördern möchten, verwenden Sie ein Wiki.
quelle
Markdown-Dateien, die mit der Quelle gehostet werden, funktionieren sehr gut.
Mit den auf RST basierenden Dokumenttools können beispielsweise HTML- oder LaTex - Dateien (und PDF - Dateien ) aus einem Dokumentensatz erstellt werden.
In diesem Fall werden Option 1 und Option 3 kombiniert.
quelle
Wenn es Ihnen nichts ausmacht, die Dokumente von Markdown in reStructuredText zu konvertieren, sollten Sie Sphinx in Betracht ziehen . Es ist genauso einfach wie Abschriften, aber viel leistungsfähiger.
quelle