Wo soll die Code-Dokumentation abgelegt werden?

Ich benutze derzeit zwei Systeme, um Code-Dokumentation zu schreiben (benutze C ++):

• Dokumentation zu Methoden und Klassenmitgliedern wird unter Verwendung des Doxygen-Formats neben dem Code hinzugefügt. Auf einem Server wird Doxygen auf den Quellen ausgeführt, sodass die Ausgabe in einem Webbrowser angezeigt werden kann
• Übersichtsseiten (die eine Reihe von Klassen, die Struktur der Anwendung, Beispielcode usw. beschreiben) werden einem Wiki hinzugefügt

Ich persönlich denke, dass dieser Ansatz einfach ist, da die Dokumentation zu Mitgliedern und Klassen dem Code sehr nahe kommt, während die Übersichtsseiten im Wiki sehr einfach zu bearbeiten sind (und es auch einfach ist, Bilder, Tabellen usw. hinzuzufügen). Mit einem Webbrowser können Sie beide Dokumentationen anzeigen.

Mein Kollege schlägt jetzt vor, alles in Doxygen abzulegen, da wir dann eine große Hilfedatei mit allem darin erstellen können (entweder mit HTML WorkShop von Microsoft oder mit Qt Assistant). Ich mache mir Sorgen, dass die Bearbeitung der Dokumentation im Doxygen-Stil viel schwieriger ist (im Vergleich zu Wiki), insbesondere wenn Sie Tabellen, Bilder usw. hinzufügen möchten (oder gibt es ein Vorschau-Tool für Doxygen, das Sie nicht generieren müssen) den Code, bevor Sie das Ergebnis sehen können?)

Womit schreiben große Open-Source- (oder Closed-Source-) Projekte ihre Codedokumentation? Teilen sie das auch auf zwischen Doxygen-Stil und einem Wiki? Oder nutzen sie ein anderes System?

Wie kann die Dokumentation am besten zugänglich gemacht werden? Über einen Webserver / Browser oder über eine große (mehrere 100MB) Hilfedatei?

Welchen Ansatz verfolgen Sie beim Schreiben der Codedokumentation?

Es kann ein echter Vorteil sein, die gesamte Dokumentation in einem System anstatt in zwei Systemen zu haben. Dinge wie Sichern und Wiederherstellen, Versionsverwaltung, globale Suche, globales Suchen und Ersetzen, Quervernetzen und, wie Sie geschrieben haben, das Zusammenführen aller Dokumente zu einem endgültigen Dokument funktionieren normalerweise mit weniger Reibung, wenn Sie nicht zwei verschiedene Dokumente verwalten müssen Systeme mit überlappenden Fähigkeiten.

Andererseits müssen Sie überlegen, ob diese Vorteile die Einfachheit Ihres Wikis überwiegen. Der Kreis Bearbeiten / Generieren / Verfeinern Bearbeiten / Erneut Generieren ist in Ihrem Wiki möglicherweise schneller. Ich vermute, dass Sie diesen Zyklus sehr schnell erreichen können, wenn Sie Ihre Übersichtsseiten als separates Sauerstoff-Teilprojekt verwalten. Sie können die externen Verknüpfungsfunktionen von doxygen nutzen. Dies ist natürlich kein Ersatz für eine "Schnellvorschau", sondern ein Schritt in diese Richtung. Bisher habe ich das noch nicht alleine gemacht, aber ich vermute, Sie müssen es selbst ausprobieren, wenn Sie wissen möchten, ob es in Ihrem Fall funktioniert.

In Bezug auf andere Projekte: Ich denke, ein Tool wie doxygen ist hauptsächlich für die Dokumentation von Bibliotheken gedacht. Wenn Sie kein Bibliotheksanbieter eines Drittanbieters sind und jeder, der Ihre Bibliotheken verwendet, uneingeschränkten Zugriff auf den Quellcode hat, ist die Notwendigkeit eines Tools wie doxygen fraglich. In unserem Team haben wir zum Beispiel fast keine externen Dokumente außerhalb des Codes außer den Endbenutzerdokumenten und den Dokumenten unserer Datenbankmodelle. Unsere Hauptwerkzeuge für diese Art von Dokumentation sind docbook und fop , was zu zufriedenstellenden Ergebnissen führt.

Verwenden Sie zuerst die Codedokumentation. Fügen Sie nach Möglichkeit Wiki und andere Methoden hinzu

Ich weiß, das wird schwierig, es aufrechtzuerhalten.

Praktische Antwort:

In der Praxis überprüfen Entwickler als Erstes den Code.

Als Entwickler habe ich gerne externe Dokumentation, wie Wiki (s), Handbücher. Aber als erstes überprüfe ich den Code (manchmal von anderen Entwicklern, manchmal von meinen eigenen).

Als Entwickler, der in mehreren Projekten und Kunden mitgearbeitet hat, füge ich so gut wie möglich externe Dokumentation hinzu, aber es ist üblich, dass ich viel Arbeit habe und kein Wiki unterstützen kann.

Manchmal interessieren sich Projektmanager und andere Vorgesetzte nicht für Dokumentation, andere Entwickler nicht.

Und das Beste, was ich tun kann, ist, dem Code einige Kommentare hinzuzufügen.

Viel Glück

Einige verwenden andere Systeme - schauen Sie sich zum Beispiel Pythons Sphinx an, sie haben ein All-in-One-Dokumentationssystem, das alles erstellt (es funktioniert auch für C / C ++).

Ich denke immer, dass Dokumentation unabhängig vom Code ist. Doxygen ist großartig, aber es dient der Übersicht über die API und nicht der 'Dokumentation'. Dafür ist ein Wiki großartig, aber ich bevorzuge es, ASCIIDOC zu verwenden und die Ergebnisse zusammen mit dem Code in der Quellcodeverwaltung zu speichern, hauptsächlich, weil ich daraus PDFs generieren kann, die ich anderen Leuten (z. B. den Testern, Kunden usw.) zur Verfügung stellen kann.

Mit Doxygen können Sie PDF-, HTML- und Wiki-Seiten erstellen, fast alles, woran Sie denken können.

Meine persönliche Präferenz ist es, sowohl Doxygen als auch Wiki und ein Skript oder etwas zu haben, um zu überprüfen, wenn sie sich unterscheiden.

Seit Version 1.8.0 unterstützt doxygen Markdown , was das Schreiben statischer Seiten ähnlich komfortabel machen sollte wie in einem Wiki-System.

Zielgruppe

Ich denke, wenn Sie diese Frage beantworten, müssen Sie sich wirklich fragen, wer diese Dokumentation lesen soll. Ein Entwickler hat ganz andere Bedürfnisse als ein Benutzer oder sogar ein Business Analyst.

• Als Entwickler: Dokumentation zum untersuchten Code, Details wie der Schnittstellenvertrag und Verwendungsbeispiele. Vielleicht einige hochrangige Dokumentationen und Protokollspezifikationen für eine gute Maßnahme.
• Als Benutzer: Dokumentation über das Hilfemenü oder eine zugängliche Website zur Verwendung der Software.
• Als Business Analyst: Dokumentationen, die als Dokumente oder als barrierefreie Website verfügbar sind, sind nützlich. Eine bescheidene Menge an Details zu Protokollen, zur Architektur auf hoher Ebene und zu Anwendungsfällen ist am besten.

Instandhaltung

Die Position der Quelle für diese Dokumentation hängt von Ihrer Zielgruppe ab und davon, wer für Ihre Zielgruppe schreibt.

• Haben Sie nur ein Haus von Entwicklern? Gib alles in den Code ein. Es wird ermutigt, es zu aktualisieren. Sie müssen an einer Kultur arbeiten, in der Aktualisierungen der Dokumentation genauso wichtig sind wie Codeänderungen.
• Haben Sie ein Haus von Entwicklern und Dokumentationsautoren? Teilen Sie die Verantwortlichkeiten. Verwenden Sie die entwicklerorientierten Tools für Entwickler und die Tools für Dokumentationsschreiber für Dokumentationsschreiber.

Stellen Sie nach Möglichkeit sicher, dass Codebeispiele oder Anwendungsfälle ausgeführt werden können. Automatisieren Sie deren Ausführung und markieren Sie Fehler intern. Wahrscheinlich handelt es sich bei diesen Seiten um eine schlechte oder schlechte Dokumentation.

Unabhängig davon, in welchen Tools Sie Ihre Dokumentation schreiben, benötigen Sie außerdem zuverlässige Mittel, um eine bestimmte Version der Dokumentation mit einer bestimmten Version des Codes zu verknüpfen. Dies ist auch in glücklichem Cloud-Land mit einer einzigen, immergrünen Bereitstellung von Vorteil.

Dokumentation einbinden

Möglicherweise ist eine Integration erforderlich, um einige Dokumentationen zu erstellen. Beachten Sie jedoch, dass nur der Benutzer von einer einzigen Stelle Zugriff auf alle benötigten Dokumentationen erwartet.

Der Geschäftsanalyst ist mit einer API-Spezifikation, Designspezifikationen und Verwendungsszenarien, die sich in separaten Dokumenten oder in separaten Abschnitten einer Website befinden, sehr zufrieden.

Der Entwickler bevorzugt alles, was von der Quelle aus sichtbar ist, freut sich jedoch über ein paar hochrangige Designdokumente und detaillierte Dokumente zur Protokollspezifikation außerhalb des Codes, vorzugsweise jedoch innerhalb derselben Kasse.

Dein Fall

Um ehrlich zu sein, handelt es sich bei der Dokumentation in Ihrem Wiki wahrscheinlich nicht um die gleiche Dokumentation in Ihrer Codebasis. Es ist möglicherweise nicht sinnvoll, das auch zu verschmelzen.

Auf der anderen Seite kann die Integration der beiden auf ein paar einfache Arten geleistet werden.

• Quelldokumentationstools (wie doxygen) können HTML-Code erzeugen, und ein Wiki befindet sich auf einem Webserver. Es wäre ein einfacher Integrationspunkt, einfach eine integrierte Version neben dem Wiki bereitzustellen und die beiden zu verbinden.
• Bei einigen Wiki-Produkten können Sie das Wiki direkt aus einer Datei ausführen, die Sie in eine Codebasis einchecken können. Dies ergibt ein einfaches Wysiwyg-Tool, während die Dokumentation mit dem Code gekoppelt bleibt.
• Andere Formate wie PDF können ebenfalls unterstützt werden, dies hängt jedoch von den spezifischen Tools ab, die Sie verwenden möchten. Es kann sinnvoll sein, Ihr Wiki in Markdown-Dateien zu kratzen und diese mit Sauerstoff (oder anderen Tools) zu versorgen. Es kann sinnvoll sein, das Wiki und den Quellcode separat als PDF-Datei zu erstellen und ein Tool zum Zusammenführen von PDF-Dateien zu verwenden.

Finden Sie am Ende des Tages heraus, welches Dokumentationssystem geringe Wartungskosten verursacht, und helfen Sie dabei, ein qualitativ hochwertiges Produkt zu liefern, wie es von Ihrer Zielgruppe aus Entwicklern, Business Analysten und Anwendern gesehen wird. Alles, was eine dieser Gruppen behindert, mindert zwangsläufig die Produktqualität.

Wenn Sie ASCII verwenden, sollten Sie Ihre versteckten Dokumentationsdaten in dem hohen Bit Ihres Quellcodes speichern! Dann haben nur die klügsten Benutzer die Möglichkeit, Ihre Dokumente zu verwenden.

Dokumentation in einem gut definierten, leicht exportierbaren, portablen Format zu haben, könnte der wahre Vorteil sein. Wenn Sphinx stirbt (unwahrscheinlich), muss ich einfach auf ein anderes System konvertieren, was meiner Meinung nach eine skriptfähige Aufgabe wäre. Das Verschieben von Daten aus dem Wiki (vermutlich in einer Datenbank in einem proprietären Format gespeichert) kann schmerzhaft sein.