Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison 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 ScummVM API-Dokumentation (Quellcode) finden Sie hier: https://doxygen.scummvm.org/modules.html
Leider fehlt es in vielen Bereichen:
1) Es hat praktisch keine Struktur, alle Informationen schweben auf derselben Ebene.
2) Die Dokumentation von C++-Elementen ist nicht einheitlich und einige davon überhaupt nicht. 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 vereinheitlicht werden. Dazu ist ein Regelwerk erforderlich, das als Grundlage für einen zukünftigen Dokumentations-Styleguide für dieses Projekt dienen könnte.
5) Das auf dieser Seite verwendete doxygen-CSS könnte verbessert werden, damit es der ScummVM-Website unter https://www.scummvm.org ähnelt.
Alle diese Probleme können während des Projekts „Season of Docs“ angegangen werden.
Diese Staffel von Docs-Anwendung wird von einem PR-Entwurf begleitet, 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 finden Sie Details zum Inhalt und den Unterschied.
In etwa sieht die PR-Abteilung Folgendes aus:
1) Was für potenzielle neue Beitragende und im Allgemeinen jeder, der sich das aktuelle API-Dokument ansieht, momentan am verwirrendsten ist, ist die mangelnde Struktur. Die Einführung einer strukturierten API-Dokumentation würde die Lesbarkeit, Auffindbarkeit und folglich die Nutzerfreundlichkeit der Dokumentation verbessern. Aus diesem Grund führt mein PR in alle Header-Dateien im Ordner "common" (Allgemein) Doxygen-Gruppen ein. Mit dieser neuen Struktur können Nutzer, die Dokumente zum betriebssystembezogenen API suchen, diese leicht in der Navigation finden.
2) Zum Erstellen dieser Dokumentation wird eine neue doxygen-Konfigurationsdatei eingerichtet.
3) Eine „links.doxyfile“-Datei, 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) Ein modifiziertes 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 auf jeden Fall bearbeitet werden muss, sind die Inhalte selbst. Damit meine ich die wesentlichen Teile des Codes, die nicht dokumentiert sind, die nicht ausreichend dokumentiert sind oder die veralteten Teile des Codes, die aus der Dokumentation entfernt werden sollten. Da ich in diesem Projekt bisher noch nicht 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 offen. Meine Idee war, dass Aktionen lauter sind als Worte. Daher beschloss ich, zu zeigen, was ich tun kann, anstatt es nur in der Anwendung zu beschreiben.
Die Organisation hat den folgenden groben Zeitplan für dieses Projekt vorgelegt: Woche 1 – Hauptaufgabe 1 – Woche 0 (vor 9/14) Vorschlagsdiskussion und Überprüfungen Woche 1 (9/14) Einrichtung des Doxygen-Builds Woche 2 (9/21) Aktualisierung des Doxygen-Skins (niedrige Priorität) Woche 3 (9/28) Allgemeiner Code – OSystem, FS, Datenstrukturen
Die einzige Änderung, die ich vorschlagen würde, besteht darin, zunächst wie bereits erwähnt an der Struktur zu arbeiten. Dies ist in den Wochen 1 und 2 möglich, zusammen mit der Doxygen-Build-Einrichtung (die größtenteils bereits erfolgt) und der Doxygen-Hautaktualisierung. Danach stimme ich zu, dass es am sinnvollsten ist, die verschiedenen Bereiche einzeln mit der beratenden Person zu besprechen, um Probleme zu identifizieren und die Doxygen-Dokumentation zu verbessern.
Ich sehe das Projekt in Standardlänge, aber ich bin mir sicher, dass es nach Abschluss des GSoD-Projekts noch andere Verbesserungen bei der API-Dokumentation gibt. Beispielsweise könnten Sie einen Dokumentations-Styleguide ausdenken und in das Wiki aufnehmen, damit Beitragende wissen, wie sie den Code dokumentieren sollten, den sie hinzufügen.
Ich helfe Ihnen gern weiter, wenn das GSoD abgeschlossen ist. Ich bin mir sicher, dass ScummVM einen technischen Redakteur beauftragen könnte, der dafür sorgt, dass das API-Dokument qualitativ hochwertig und nutzerfreundlich 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.