Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo progetto
- Organizzazione open source:
- CERN-HSF
- Redattore tecnico:
- LuckInTheRain
- Nome del progetto:
- Documentazione ROOT: analisi, ristrutturazione e riscrittura
- Durata del progetto:
- A lungo termine (5 mesi)
Project description
Il progetto prevede quattro fasi:
1.) Analisi della documentazione ROOT corrente
Il documento ROOT completo (sito web, guida dell'utente, riferimento C++, tutorial ecc.) viene analizzato e verificato in base ai seguenti criteri: struttura, modularizzazione, standardizzazione, meccanismi di accesso, coerenza, tipi di informazioni utilizzati, preparazione e comprensibilità specifiche del gruppo target. L'obiettivo è creare un concetto per la gestione delle informazioni, una matrice per la strutturazione e una linea guida per la standardizzazione dei contenuti.
2.) Definizione di un metodo per strutturare la documentazione di un software di scrittura con il team di ROOT
Il team ROOT viene presentato a DITA (Darwin Information Typing Architecture), uno standard OASIS per la documentazione del software (https://www.oasis-open.org/committees/dita/). L'obiettivo principale è capire come strutturare i contenuti specifici del software e come i tipi di informazioni di base come "concetto", "attività" e "riferimento" vengono utilizzati per scrivere la documentazione del software.
3.) Ristrutturazione e riorganizzazione della documentazione ROOT
In base ai risultati dei primi due passaggi, la documentazione ROOT viene ristrutturata e modularizzata in base a gruppi di destinazione, ruoli e casi d'uso e i contenuti vengono assegnati agli elementi e ai tipi di contenuti corrispondenti (sito web, guida per gli utenti, riferimento C++, tutorial e così via). Poiché le informazioni a disposizione sono molto ampie, è necessario definire una struttura di riferimento coerente. L'obiettivo è fornire una panoramica completa e mostrare agli utenti modi chiari per utilizzare ROOT in base alle loro esigenze. Inoltre, viene fornita un'introduzione compatta non orientata alla fisica.
4.) Riscrivere la documentazione di ROOT
Le parti principali della documentazione, in particolare la Guida dell'utente, vengono riscritte in conformità con l'approccio DITA. Le regole di strutturazione e scrittura vengono registrate in una guida di stile per garantire la coerenza dei documenti in futuro. L'obiettivo è consentire al team di ROOT di estendere e gestire la documentazione di ROOT in futuro.
Tempi stimati (5 mesi):
Fase 1: analizza la documentazione ROOT attuale: 3 settimane.
Fase 2: definizione di un metodo per strutturare la documentazione di scrittura del software con il team ROOT: 2 settimane.
Fase 3: ristrutturazione e riorganizzazione della documentazione ROOT: 4 settimane.
Fase 4: riscrittura della documentazione ROOT: 11 settimane.