Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- CERN-HSF
- Technical writer:
- LuckInTheRain
- Nome progetto:
- Documentazione ROOT: analisi, ristrutturazione e riscrittura
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
Il progetto si compone di quattro fasi:
1. Analisi della documentazione ROOT attuale
Il documento ROOT completo (sito web, guida dell'utente, riferimento C++, tutorial ecc.) viene analizzato e controllato in base ai seguenti criteri: struttura, modularizzazione, standardizzazione, meccanismi di accesso, coerenza, tipi di informazioni utilizzate, preparazione e comprensibilità specifiche per il gruppo target. L'obiettivo è creare un concetto per la gestione delle informazioni, una matrice per strutturare e una linea guida per standardizzare i contenuti.
2.) Definizione di un metodo per strutturare una documentazione del software di scrittura con il team ROOT
Presenta al team ROOT il DITA (Darwin Information Typing Architecture), uno standard OASIS per la documentazione del software (https://www.oasis-open.org/committees/dita/). L'attenzione si concentra principalmente sulla comprensione di come strutturare contenuti specifici del software e di come i tipi di informazioni elementari come "concetto", "compito" 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 riorganizzata e modularizzata in base a gruppi di destinazione, ruoli e casi d'uso e i contenuti vengono assegnati agli elementi corrispondenti (sito web, guida dell'utente, riferimenti a C++, tutorial ecc.) e tipi di contenuti. Poiché le informazioni disponibili sono molto ampie, è necessario stabilire anche una struttura di riferimento coerente. L'obiettivo è fornire una panoramica completa e mostrare agli utenti modi chiari in che modo possono utilizzare ROOT per le loro esigenze. Viene inoltre fornita un'introduzione compatta non incentrata sulla fisica.
4.) Riscrittura della documentazione ROOT
Le parti principali della documentazione, in particolare la Guida dell'utente, vengono riscritte secondo 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 ROOT di estendere e gestire autonomamente la documentazione ROOT in futuro.
Pianificazione del tempo (5 mesi):
Fase 1. Analisi della documentazione ROOT attuale: 3 settimane.
Fase 2: definizione di un metodo per la strutturazione di una documentazione software di scrittura con il team ROOT: 2 settimane.
Fase 3: ristrutturazione e riorganizzazione della documentazione ROOT: 4 settimane.
Fase 4. Riscrittura della documentazione ROOT: 11 settimane.