Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- ScummVM
- Technischer Redakteur:
- b-gent
- Projektname:
- Quellcodedokumentation mit Doxygen verbessern
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Die aktuelle Quellcode-Dokumentation zum ScummVM API finden Sie hier: https://doxygen.scummvm.org/modules.html
Leider fehlt es in vielen Bereichen:
1) Es gibt praktisch keine Struktur, alle Informationen schweben auf derselben Ebene.
2) Die Dokumentation von C++-Elementen ist nicht einheitlich und einige davon überhaupt nicht dokumentiert. Dies ist etwas, das die Organisation als eines der Hauptprobleme erwähnt.
3) Veraltete und eingestellte Inhalte werden weiterhin in der Ausgabe angezeigt.
4) Sprache und Verwendung von Doxygen-Tags sollten einheitlicher gestaltet werden. Dafür ist ein Regelsatz erforderlich, der als Grundlage für einen zukünftigen Styleguide für die Dokumentation für dieses Projekt dienen könnte.
5) Die auf dieser Seite verwendete doxygen-CSS könnte verbessert werden, sodass sie der ScummVM-Website unter https://www.scummvm.org ähnelt.
Alle diese Probleme können mit dem „Season of Docs“-Projekt angegangen werden.
Zu dieser "Season of Docs"-Anwendung gibt es einen PR-Entwurf, den ich im Projekt geöffnet habe, um einige von mir vorgeschlagene Verbesserungen zu demonstrieren: https://github.com/scummvm/scummvm/pull/2361 In der Beschreibung findest du Details zum Inhalt und zum Anzeigen des Unterschieds.
Das ist ungefähr das, was die PR umfasst:
1) Was für potenzielle neue Beitragende, und im Allgemeinen bei allen, die sich das aktuelle API-Dokument ansehen, momentan am verwirrendsten ist, ist die mangelnde Struktur. Die Einführung einer strukturierten API-Dokumentation würde die Lesbarkeit, Auffindbarkeit und folglich die Nutzerfreundlichkeit des Dokuments verbessern. Deshalb fügt mein PR in alle Header-Dateien im Ordner „common“ doxygen Groups ein. Mit dieser neuen Struktur können Nutzer, die beispielsweise Dokumente für ein betriebssystembezogenes API suchen, ganz einfach in der Navigation finden.
2) Es wird eine neue doxygen-Konfigurationsdatei eingerichtet, um die Erstellung dieser Dokumentation zu ermöglichen.
3) Eine Datei „links.doxyfile“, aus der alle in der Dokumentation verwendeten Links aus einer einzigen Quelle stammen können. Ein nützlicher Mechanismus bei der Arbeit mit Doxygen.
4) Eine modifizierte doxygen-CSS. Sie stammt derzeit aus einem anderen Open-Source-Projekt und ist nur ein Ausgangspunkt. Idealerweise sollte das Erscheinungsbild der Doxygen-Seite mehr oder weniger mit der ScummVM-Webseite übereinstimmen.
Was in der PR nicht behandelt wird, aber definitiv bearbeitet werden muss, sind der Inhalt selbst. Damit meine ich die wesentlichen Teile des Codes, die nicht dokumentiert sind, diejenigen, die nicht ausreichend dokumentiert sind, oder die veralteten Teile des Codes, die aus der Dokumentation entfernt werden sollten. Da ich bisher noch nicht an dem Projekt gearbeitet habe, benötige ich hierfür die Hilfe einer beratenden Person.
Ob wir etwas aus der PR umsetzen, bleibt natürlich mit der Organisation abgesprochen. Meine Idee war, dass Aktionen lauter sprechen als Worte. Also beschloss ich, zu zeigen, was ich tun kann, anstatt es einfach in der Anwendung zu beschreiben.
Die Organisation hat den folgenden groben Zeitplan für dieses Projekt vorgelegt: Woche 1 – Hauptaufgabe / Woche 1 – Backend 1 – Backend 1 – Wochen 1 – 1 / vor 14 Wochen 1 – Backend 14) Vorschlagsdiskussion und Rezensionen Woche 1 (9/14) Doxygen-Build einrichten Woche 2 (9/21) Aktualisierung des Doxygen-Skins (niedrige Priorität) Woche 3 (9/28) Allgemeiner Code – Woche 1 / Woche 1 – Allgemeiner Code – Woche 1 – allgemeines OSystem, Grafik 0. Tag 0.
Die einzige Änderung, die ich vorschlagen würde, besteht darin, wie bereits erwähnt zuerst an der Struktur zu arbeiten. Dies ist in den Wochen 1 und 2 möglich, zusammen mit der Einrichtung des Doxygen-Builds, die größtenteils bereits erfolgt ist, und der Doxygen-Hautaktualisierung. Danach stimme ich zu, dass es am sinnvollsten ist, die verschiedenen Bereiche einzeln mit der beratenden Person durchzugehen, um Probleme zu identifizieren und die Doxygen-Dokumentation zu verbessern.
Ich sehe das Projekt als Projekt in Standardlänge, aber ich bin mir sicher, dass es nach Abschluss des GSoD-Projekts noch andere Verbesserungen in der API-Dokumentation gibt. Zum Beispiel entwickeln Sie einen Dokumentations-Styleguide und fügen ihn zum Wiki hinzu, damit Beitragende wissen, wie sie den von ihnen hinzugefügten Code dokumentieren sollten.
Ich helfe Ihnen gern weiter, auch wenn GSoD vorbei ist. Ich bin sicher, dass ScummVM einen technischen Redakteur beauftragen könnte, der sicherstellen wird, dass das API-Dokument qualitativ hochwertig und nutzungsfreundlich ist. Ich sehe auch, dass es noch andere zukünftige Dokumentprojekte gibt, bei denen ich Ihnen helfen könnte, z. B. das Erstellen eines Leitfadens zur Arbeit mit Plug-ins.