Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- CERN-HSF
- Technischer Redakteur:
- LuckInTheRain
- Projektname:
- ROOT Documentation: Analyzing, Restructuring and Rewriting
- Projektdauer:
- Langfristig (5 Monate)
Projektbeschreibung
Das Projekt besteht aus vier Phasen:
1. Aktuelle ROOT-Dokumentation analysieren
Das vollständige ROOT-Dokument (Website, Bedienungsanleitung, C++-Referenz, Anleitungen usw.) wird anhand der folgenden Kriterien analysiert und geprüft: Strukturierung, Modularisierung, Standardisierung, Zugriffsmechanismen, Einheitlichkeit, verwendete Informationstypen, zielgruppenspezifische Vorbereitung und Verständlichkeit. Ziel ist es, ein Konzept für die Informationsverwaltung, eine Strukturmatrix und eine Richtlinie für die Standardisierung der Inhalte zu erstellen.
2.) Definition einer Methode zur Strukturierung einer Softwaredokumentation mit dem ROOT-Team
Dem ROOT-Team wird DITA (Darwin Information Typing Architecture), ein OASIS-Standard für Softwaredokumentation (https://www.oasis-open.org/committees/dita/), vorgestellt. Der Schwerpunkt liegt darauf, zu verstehen, wie softwarespezifische Inhalte strukturiert werden und wie grundlegende Informationstypen wie „Konzept“, „Aufgabe“ und „Referenz“ beim Erstellen von Softwaredokumentation verwendet werden.
3.) Umstrukturierung und Neuorganisation 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, Benutzerhandbuch, C++-Referenz, Tutorials usw.) und Inhaltstypen zugewiesen. Da die verfügbaren Informationen sehr umfangreich sind, muss auch eine einheitliche Referenzstruktur festgelegt werden. Ziel ist es, einen umfassenden Überblick zu geben und Nutzenden aufzuzeigen, wie sie ROOT für ihre Anforderungen einsetzen können. Außerdem wird eine kompakte, nicht physikorientierte Einführung angeboten.
4.) ROOT-Dokumentation umschreiben
Die wichtigsten Teile der Dokumentation, insbesondere das Handbuch, werden gemäß dem DITA-Ansatz umgeschrieben. Die Strukturierungs- und Schreibregeln werden in einem Styleguide festgehalten, um für Einheitlichkeit in den Dokumenten zu sorgen. Ziel ist es, dass das ROOT-Team die ROOT-Dokumentation in Zukunft selbst erweitern und pflegen kann.
Geschätzter Zeitplan (5 Monate):
Phase 1: Analyse der aktuellen ROOT-Dokumentation: 3 Wochen
Phase 2: Definition einer Methode zur Strukturierung einer Softwaredokumentation mit dem ROOT-Team: 2 Wochen.
Phase 3: Neustrukturierung und Neuorganisation der ROOT-Dokumentation: 4 Wochen
Phase 4: Neuschreiben der ROOT-Dokumentation: 11 Wochen.