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:
- CERN-HSF
- Technischer Redakteur:
- LuckInTheRain
- Projektname:
- ROOT-Dokumentation: Analysieren, Umstrukturieren und Umschreiben
- Projektdauer:
- Langfristig (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 folgender 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 zur Standardisierung der Inhalte zu erstellen.
2.) Definieren einer Methode zum Strukturieren einer Softwaredokumentation 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 wie „Konzept“, „Aufgabe“ und „Referenz“ zum Schreiben von Softwaredokumentation verwendet werden.
3.) Restrukturierung und Reorganisation der ROOT-Dokumentation
Basierend auf den Ergebnissen der ersten beiden Schritte wird die ROOT-Dokumentation nach Zielgruppen, Rollen und Anwendungsfällen neu strukturiert und 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 geschaffen werden. Ziel ist es, einen umfassenden Überblick zu geben und den Nutzenden klar aufzuzeigen, wie sie ROOT für ihre Anforderungen einsetzen können. Außerdem gibt es eine kompakte Einführung, die sich nicht mit Physik beschäftigt.
4.) ROOT-Dokumentation neu schreiben
Die Hauptteile der Dokumentation, insbesondere das Nutzerhandbuch, wurden entsprechend dem DITA-Ansatz umgeschrieben. Die Strukturierungs- und Schreibregeln werden in einem Styleguide aufgezeichnet, um zukünftige Konsistenz in den Dokumenten zu gewährleisten. Das 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: Aktuelle ROOT-Dokumentation analysieren: 3 Wochen.
Phase 2: Definieren einer Methode für die Strukturierung einer Schreibsoftwaredokumentation mit dem ROOT-Team: 2 Wochen.
Phase 3: Restrukturierung und Reorganisation der ROOT-Dokumentation: 4 Wochen.
Phase 4: Überarbeitung der ROOT-Dokumentation: 11 Wochen.