Wir betrachten die Dokumentation eines jungen open source project, und ich hoffte auf einige Vorschläge für gute Methoden und Werkzeuge, die gut für Sie gearbeitet haben. Als Entwickler bevorzugen Sie außerdem Online-Dokumente, Wiki-basierte Dokumente, Hilfedateien oder andere?Empfehlungen für die Dokumentation mit einem Open-Source-Projekt?
Da Ihre Anwendung in C# entwickelt wird, sehen Sie sich Doxygen zum Generieren Ihrer API-Dokumentation an. Es ist extrem leistungsfähig (es führt die Standard-Dokumentation im Javadoc-Stil durch, erzeugt aber auch Aufrufe, Vererbung, Dateiabhängigkeit und Kollaborationsgraphen). Trotz seiner Kraft ist es einfach zu bedienen. Es kann API-Dokumente in unzähligen Formaten generieren: HTML, Latex, Manpage, etc.
Schreiben Sie zum Erstellen von Handbüchern, Lernprogrammen und anderen flexibleren Dokumentationsarten ernsthaft das Einrichten eines Wikis. Ich habe DokuWiki mit sehr viel Erfolg verwendet. Es hat Unterstützung für Syntax-Highlighting, also ist es gut für Code-Projekte. Es hat auch Benutzer-ACLs, die für ein Open-Source-Projekt nützlich sein werden. Es erfordert auch nur PHP und keine Datenbank. Natürlich bietet es die Standard-Wiki-Funktionen wie Versionierung.
Schließlich sollte ich trac erwähnen, die ein Wiki, Versionskontrolle, Bug-Tracker-Hybrid ist. Es ist definitiv einen Blick wert.
Während ich noch keine Open-Source-Projekte gesponsert habe, ist die meiste Arbeit, die ich mache, kollaborativ. Ich habe festgestellt, dass ein Wiki mit entsprechenden Berechtigungen eine ausgezeichnete Möglichkeit für die Zusammenarbeit beim Schreiben gemeinsamer Dokumente ist. In meinem Fall sind es typischerweise Entwicklungsgeschichten - ich und der Kunde arbeiten daran, diese zu generieren. Ich würde denken, dass dies auch mit der kollaborativen Dokumentation für Ihr Projekt funktionieren würde.
Ich mag die Idee eines Wikis, besonders für seine Zusammenarbeit. – ccook
Sounds wie Sandcastle wäre eine gute Passform für Sie.
Der allumfassende Weg, den ich bevorzuge, ist die Verwendung eines Wikis. Ich mag jedoch die automatische Generierung von Dokumenten aus dem Quellcode. Es gibt viele Werkzeuge da draußen, aber ich mag besonders SandCastle. Es bietet den gleichen Stil wie in MSDN-Dokumenten, mit denen die meisten .NET-Entwickler bereits Erfahrung haben sollten, und es scheint, dass Ihr Open Source-Projekt in .NET integriert ist. Soweit ich sehen kann, ist .NET 2.0 das neueste unterstützte Framework.
Online-Dokumente sind immer eine gute Idee, besonders wenn sie auf Wiki basieren. Sie sind besser recherchierbar, es gibt eine Geschichte, die im Falle von Fehlern aufbewahrt wird, und sie sind in der Regel kürzer, da sie nicht den "Zucker" einer langen Dokumentation oder Anleitung haben. Bei der Benennung von Artikeln und Links ist jedoch besondere Vorsicht geboten.
Wenn bestimmte Teile des Projektcodes jedoch als APIs dienen, muss das entsprechende Wissen im Code erfasst werden, damit es für diejenigen sichtbar ist, die es mit dem IDE-Mechanismus "Mauszeiger über einen Aufruf" untersuchen. Die Delokalisierung von Wissen ist ein großes Problem, und die Leute zögern generell, einen Kontextwechsel vorzunehmen. Wenn etwas in der Dokumentation der Funktionskopfzeile erscheint, hat es eine höhere (wenn auch nicht so hohe) Chance, jemals gelesen zu werden, als wenn es anderswo erscheint.
Wenn Sie die Funktionskopfdokumentation schreiben, konzentrieren Sie sich auf Anweisungen - Dinge, die den Client direkt betreffen. Diese können zwingend sein (z. B. zuerst X anrufen) oder informativ sein (z. B. sich bewusst sein, dass X ... ist).
Sehen Sie, wie die anderen do it (Big Opensource Projekte meine ich)
Aber für mich abgesehen von der Wiki (von anderen Plakaten erwähnt) einige official Dokumentation ist alw Ays benötigt für strukturelle/Richtlinie Zeug. Das Wiki ist mehr für knowledge base Zeug IMHO
Ich persönlich mag Sphinx für Entwickler geschriebene Dokumentation, teilweise wegen wie schön die Dokumentation in es aussieht. Es verarbeitet Dokumente, die in ReST geschrieben wurden, in LaTeX (zum Drucken/PDF) oder HTML.
Ich würde nicht nur mit einem API-Dokumentationswerkzeug wie Doxygen empfehlen. Es ist großartig, wenn das auch verwendet wird, aber es sollte nicht die einzige Form der Dokumentation sein.
Je nachdem, wie aktiv Ihre Benutzergemeinschaft ist, würde ich auch empfehlen, ein Wiki für Rezepte oder andere Tutorials hinzuzufügen. Der Inhalt kann dann in die von Sphinx verwendete ReST-Dokumentation eingefügt werden.
möglich Duplikat von [Erstellen von großen API-Dokumentation: Tools und Techniken] (http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques) – Mark
Diese Frage wurde ein Jahr gestellt vor dem "Duplikat" :) – ccook