Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- CERN-HSF
- Pisarz techniczny:
- LuckInTheRain
- Nazwa projektu:
- Dokumentacja ROOT: analiza, zmiana struktury i pisanie
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
Projekt obejmuje 4 fazy:
1) Analizowanie bieżącej dokumentacji ROOT
Cały dokument ROOT (witryna internetowa, przewodnik użytkownika, materiały w języku C++, samouczki itp.) jest analizowany i sprawdzany pod kątem następujących kryteriów: struktura, modularyzacja, standaryzacja, mechanizmy dostępu, spójność, wykorzystywane typy informacji, przygotowanie i przystępność treści pod kątem konkretnej grupy docelowej. Celem jest opracowanie koncepcji zarządzania informacjami i schematu ich struktury oraz wskazówki na temat standaryzacji treści.
2.) Opracowanie metody tworzenia struktury dokumentacji oprogramowania z zespołem ROOT
Zespół ROOT przedstawia DITA (Darwin Information Typing Architecture) standard OASIS dla dokumentacji oprogramowania (https://www.oasis-open.org/committees/dita/). Chodzi przede wszystkim o zrozumienie, jak tworzyć strukturę treści z konkretnego oprogramowania i jak podstawowe typy informacji, takie jak „koncepcja”, „zadanie” i „dokumentacja”, są używane przy tworzeniu dokumentacji oprogramowania.
3.) Zmiana struktury i organizacji dokumentacji ROOT
Na podstawie wyników z 2 pierwszych etapów dokumentacja ROOT została uporządkowana i modularowana według grup docelowych, ról i przypadków użycia. Zawartość została przypisana do odpowiednich elementów (strona internetowa, przewodnik użytkownika, materiały referencyjne C++, samouczki itp.) i typów treści. Dostępne informacje są bardzo obszerne, dlatego należy też zadbać o spójną strukturę plików referencyjnych. Celem jest zapoznanie się z ogólnymi informacjami oraz wskazanie użytkownikom, w jaki sposób mogą korzystać z ROOT w celu zaspokojenia ich potrzeb. Dodatkowo dostępne jest zwięzłe wprowadzenie, które nie dotyczy fizyki.
4.) Przeredagowanie dokumentacji ROOT
Główne części dokumentacji, zwłaszcza Przewodnik użytkownika, są napisane ponownie zgodnie z zasadami DITA. Zasady porządkowania i pisania są odnotowywane w przewodniku stylów, aby zapewnić spójność w przyszłych dokumentach. Celem jest umożliwienie zespołowi ROOT samodzielnego rozszerzania i utrzymywania dokumentacji ROOT w przyszłości.
Szacowany harmonogram (5 miesięcy):
Etap 1. Analiza bieżącej dokumentacji ROOT: 3 tygodnie
Etap 2. Określenie metody porządkowania dokumentacji oprogramowania do pisania przez zespół ROOT: 2 tygodnie.
Etap 3. Zmiana struktury i reorganizacja dokumentacji ROOT: 4 tygodnie
Etap 4. Przepisanie dokumentacji ROOT: 11 tygodni.