Das Erstellen einer C ++ - Bibliothek bedeutet auch, sie zu dokumentieren, damit andere sie verwenden können, und die Qualität der Dokumentation kann erheblich variieren.
Wie sollte eine Website für eine C ++ - Bibliothek so strukturiert sein, dass sie am effektivsten ist?
Ich würde "am effektivsten" als auf drei spezifische Gruppen von Bibliotheksakteuren aufgeteilt bezeichnen, die jeweils in der Lage sein sollten, zu finden und zu lernen, was sie benötigen, um an der Bibliothek teilzunehmen und sie zu nutzen:
Neue Benutzer benötigen eine hervorragende, einfache Einführung, Download, Einrichtung und Dokumentation, die eindeutig von einem Schritt zum nächsten fließt.
Erfahrene Benutzer benötigen eine solide Referenz mit schnellem Zugriff auf die benötigten Details und eindeutigen Informationen zu neuen Updates.
Neue Mitwirkende benötigen eine Anleitung, die die Schritte abdeckt, die sie unternehmen müssen, um ihre Beiträge in die Bibliothek zu bringen.
Ich möchte herausfinden, wie ich jeden mit dem, was er sieht und benutzt, sehr glücklich machen kann. Diese Frage ist eine Mischung aus professioneller Programmierung und Benutzererfahrung.
Für bestimmte Beispiele ist Boost eine der besten Sammlungen von Bibliotheken, aber die Erstinstallation, die Referenzdokumentation und das Herausfinden, wie man dazu beiträgt, können etwas verwirrend sein.
Andererseits habe ich festgestellt, dass cppreference.com und die SGI STL- Dokumentation mit Erklärungen, Links und Beispielen sehr klar und nützlich sind.
Während es sich bei den Beispielen lediglich um Meinungen handelt und andere davon abweichen können, hilft dies, der von mir gestellten Frage einen Kontext zu geben.
quelle
Antworten:
In meiner vorherigen Firma haben wir begonnen, Dokumentation zu generieren und jeden Abend einen CI-Job ausführen zu lassen und ihn als eine Reihe von Webseiten zu veröffentlichen, auf die sich das Wiki unseres Teams dann beziehen würde.
Wie in den Kommentaren zu Ihrer Frage vorgeschlagen, haben wir Sauerstoff verwendet. Eine Sache, die mir sehr gut gefallen hat und die in Version 1.8 eingeführt wurde, war die Möglichkeit, ein Verzeichnis (oder einen ganzen Baum) von Markdown-Dokumenten zu haben, während zuvor Sauerstoff ausschließlich aus Quelldateien generiert wurde.
Die Struktur, die wir hatten, war ein Begrüßungsbildschirm (Markdown), der Links zu verschiedenen Orten enthielt. Eine davon war eine Produktarchitektur, die eine 30.000-Fuß-Ansicht des Produkts zeigte und wichtige Dienstleistungen hervorhob. Dann gab es von dieser Seite Likes zu anderen Markdown-Seiten, die jeden der Dienste erweiterten und ein sehr hochwertiges Design von jedem präsentierten (10k Fußansicht?).
Außerdem hatten wir auf der Hauptseite Links zu Sammlungen von Benutzerhandbüchern, die wir geschrieben haben, um zu erklären, wie ein allgemeiner Dienstprogramm- / Framework-Code verwendet wird.
Und wir begannen langsam, vorhandene Designdokumente (in MS Word geschrieben und in Share Point gespeichert) in das Sauerstoffformat zu migrieren, was sich tatsächlich als einfacher erwies, als man erwarten würde. Ohne die Diagramme, die einzeln exportiert und als JPEGs gespeichert werden mussten, konnte ein 20-30-seitiges Designdokument in etwa 15-30 Minuten in das Sauerstoff-Markup-Format konvertiert werden, und es war so einfach, dass ein Koop dies tun konnte ( *) .
Das Schöne an der Verwendung von Doxygen für diese Art von Dokumentation war, dass wir alle unsere Dokumentationen direkt mit Klassen- / Funktionsreferenzseiten verknüpfen konnten, die durch das Parsen von Header-Dateien generiert wurden. Es war also eine sehr schöne Struktur, die von "Willkommen" -> "Architektur" -> "Design" -> bis hin zur Dokumentation auf Klassenebene reichte.
Und da sich das Ganze in einem Abschlag befand, war es sehr einfach, Inhalte zu generieren (viel einfacher als zu versuchen, einem Team von Ingenieuren zu erklären, wie man MS Word-Stile richtig verwendet), und die Dokumentation wurde genau dort mit dem Quellcode eingecheckt Es wurden neue Versionen eingeführt und Design / Architektur geändert. Die Dokumentation blieb immer auf dem neuesten Stand.
(*) - j / k Wir hatten (größtenteils) großartige Kooperationen und sie haben viele großartige Beiträge zum Produkt geleistet, aber ich habe einen von ihnen dazu gebracht, einen Teil der Dokumentkonvertierung durchzuführen.
quelle