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:
- CERN-HSF
- Technischer Redakteur:
- LuckInTheRain
- Projektname:
- ROOT-Dokumentation: Analysieren, Restrukturieren und Umschreiben
- Projektdauer:
- Lange Ausführung (5 Monate)
Projektbeschreibung
Das Projekt besteht aus vier Phasen:
1. Aktuelle ROOT-Dokumentation analysieren
Das vollständige ROOT-Dokument (Website, Nutzerhandbuch, C++-Referenz, Tutorials usw.) wird anhand der folgenden Kriterien analysiert und geprüft: Struktur, Modularisierung, Standardisierung, Zugangsmechanismen, Konsistenz, verwendete Informationstypen, zielgruppenspezifische Vorbereitung und Verständlichkeit. Ziel ist es, ein Konzept für das Informationsmanagement sowie eine Matrix für die Strukturierung und eine Richtlinie für die Standardisierung der Inhalte zu erstellen.
2. Definieren einer Methode zum Strukturieren einer Schreibsoftwaredokumentation mit dem ROOT-Team
DITA (Darwin Information Typing Architecture), ein OASIS-Standard für die Softwaredokumentation (https://www.oasis-open.org/committees/dita/) wird dem ROOT-Team vorgestellt. Der Schwerpunkt liegt darauf, zu verstehen, wie softwarespezifische Inhalte strukturiert werden können und wie grundlegende Informationstypen als „Konzept“, „Aufgabe“ und „Referenz“ für das Schreiben von Softwaredokumentationen verwendet werden.
3. Restrukturierung und Reorganisation der ROOT-Dokumentation
Basierend auf den Ergebnissen der ersten beiden Schritte wird die ROOT-Dokumentation neu strukturiert und nach Zielgruppen, Rollen und Anwendungsfällen modularisiert. Die Inhalte werden den entsprechenden Elementen (Website, Nutzerhandbuch, C++-Referenz, Tutorials usw.) und Inhaltstypen zugewiesen. Da die verfügbaren Informationen sehr umfangreich sind, muss auch eine einheitliche Referenzstruktur festgelegt werden. Das Ziel ist, einen umfassenden Überblick zu geben und den Nutzenden klar zu zeigen, wie sie ROOT für ihre Anforderungen verwenden können. Außerdem gibt es eine kompakte, nicht physikorientierte Einführung.
4. ROOT-Dokumentation neu schreiben
Die Hauptteile der Dokumentation, insbesondere das Nutzerhandbuch, wurden entsprechend dem DITA-Ansatz umformuliert. Die Strukturierungs- und Schreibregeln werden in einem Styleguide aufgezeichnet, um zukünftig Konsistenz in den Dokumenten zu gewährleisten. Ziel ist es, dem ROOT-Team die Möglichkeit zu geben, die ROOT-Dokumentation in Zukunft selbst zu erweitern und zu pflegen.
Geschätzter Zeitaufwand (5 Monate):
Phase 1: Analysieren der aktuellen ROOT-Dokumentation: 3 Wochen.
Phase 2: Definieren einer Methode zur Strukturierung einer Schreibsoftwaredokumentation mit dem ROOT-Team: 2 Wochen.
Phase 3: Umstrukturierung und Reorganisation der ROOT-Dokumentation: 4 Wochen.
Phase 4: Umschreiben der ROOT-Dokumentation: 11 Wochen.