Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source
- CERN-HSF
- Pisarz techniczny:
- LuckInTheRain
- Nazwa projektu:
- Dokumentacja ROOT: analizowanie, restrukturyzacja i przepisywanie
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
Projekt składa się z 4 etapów:
1) Analiza bieżącej dokumentacji ROOT
Cały dokument ROOT (strona internetowa, przewodnik użytkownika, podręcznik C++, samouczki itp.) jest analizowany i sprawdzany pod kątem następujących kryteriów: strukturyzacji, modułowości, standaryzacji, mechanizmów dostępu, spójności, używanych typów informacji, przygotowania pod kątem grupy docelowej oraz zrozumiałości. Celem jest opracowanie koncepcji zarządzania informacjami, a także struktury i wytycznych dotyczących standaryzacji treści.
2) Określanie metody tworzenia struktury dokumentacji oprogramowania z zespołem ROOT
Zespół ROOT przedstawia DITA (Darwin Information Typing Architecture), standard OASIS na potrzeby dokumentacji oprogramowania (https://www.oasis-open.org/committees/dita/). Głównym celem jest zrozumienie, jak uporządkować treści w przypadku danego oprogramowania i jak podstawowe typy informacji, takie jak „koncepcja”, „zadanie” i „odniesienie”, są wykorzystywane w tworzeniu dokumentacji oprogramowania.
3) Zmiana struktury i reorganizacja dokumentacji ROOT
Na podstawie wyników z pierwszych 2 etapów dokumentacja ROOT zostaje przebudowana i zmodyfikowana pod kątem grup docelowych, ról i przypadków użycia. Treści są przypisywane do odpowiednich elementów (strona internetowa, przewodnik użytkownika, podręcznik C++, samouczki itp.) i typów treści. Ze względu na to, że dostępne informacje są bardzo obszerne, należy również stworzyć spójną strukturę referencyjną. Celem jest przedstawienie wyczerpującego przeglądu i jasnych sposobów korzystania z ROOT przez użytkowników. Dodatkowo udostępniamy zwięzłe wprowadzenie, które nie wymaga znajomości fizyki.
4) Przepisywanie dokumentacji ROOT
Główne części dokumentacji, zwłaszcza Przewodnik użytkownika, zostały na nowo napisane zgodnie z podejściem DITA. Reguły struktury i pisania są rejestrowane w Przewodniku stylistycznym, aby zapewnić spójność dokumentów w przyszłości. Celem jest umożliwienie zespołowi ROOT samodzielnego rozszerzania i utrzymywania dokumentacji ROOT w przyszłości.
Przewidywany harmonogram (5 miesięcy):
Etap 1. Analiza bieżącej dokumentacji ROOT: 3 tygodnie.
Etap 2. Określanie metody tworzenia dokumentacji oprogramowania z zespołem ROOT: 2 tygodnie.
Etap 3. Zmiana struktury i reorganizacja dokumentacji ROOT: 4 tygodnie.
Etap 4. Przeredagowanie dokumentacji ROOT: 11 tygodni.