Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.
Riepilogo del progetto
- Organizzazione open source:
- CERN-HSF
- Technical writer:
- Gianni
- Nome progetto:
- CERN-HSF - Documentazione ROOT per l'adozione di segmenti di pubblico generici, associazioni Python dinamiche e tutorial
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
CERN-HSF - Documentazione ROOT per l'adozione di un pubblico generico, associazioni Python dinamiche e tutorial Mentor: Olivier Couet, Axel Naumann
Abstract: La documentazione è essenziale per un'adozione efficace ed efficiente del software da parte degli utenti. Una documentazione per l'utente chiara, accurata e completa migliora la competenza degli utenti con il software mentre cercano di raggiungere i loro obiettivi. Su queste linee, esempi e tutorial espliciti sono strumenti potenti che consentono agli utenti di imparare rapidamente.
Mentre esaminiamo l'uso di ROOT da parte di fisici, ricercatori e sviluppatori all'interno dello spazio di analisi dei dati e visualizzazione per la fisica, abbiamo notato i vantaggi di una documentazione facile da usare e aggiornata. In particolare, grazie all'ampiezza del codice sorgente e alla sua crescita, il sistema di documentazione può trarre vantaggio da un'evoluzione parallela per concedere agli utenti la possibilità di massimizzare tutto ciò che ROOT ha da offrire.
Riepilogo e analisi della documentazione corrente Attualmente, la documentazione per l'utente offre una guida che consente ai fisici di adottare ROOT più facilmente rispetto a un pubblico generico. Inoltre, all'interno di determinati argomenti come le associazioni Python dinamiche, potrebbero essere apportati miglioramenti per una documentazione più completa e chiara. Analogamente, il nuovo formato di dati RNTuple è privo delle specifiche dettagliate necessarie. Infine, nella documentazione attuale mancano i tutorial relativi a ROOT 7.
Metodologia: dopo aver consultato Olivier, è emerso che, per risolvere i problemi sopra citati, l'obiettivo principale dovrebbe consistere nell'identificare le lacune di conoscenza tra i ricercatori specializzati e un pubblico generale, creare documentazione per colmare questa lacuna, scrivere una documentazione più dettagliata delle associazioni Python dinamiche, implementare "tutorial per l'analisi moderna" per ROOT 7 e creare specifiche tecniche dettagliate per RNTuple. In questo modo, durante questo processo, la documentazione potrebbe incorporare blocchi note Jupyter in modo che strumenti di apprendimento tangibili e interattivi possano aiutare gli utenti.
Sequenza temporale: Si stima che le fasi del progetto siano: Identificare le lacune nelle conoscenze tra ricercatori specializzati e un pubblico generico (durante la lettura dell'attuale documentazione e del codice sorgente) → 1-2 settimane Creare e ridefinire la documentazione per colmare questa lacuna → 3 settimane Scrivere una documentazione più dettagliata sulle associazioni Python dinamiche → 3 settimane Implementare tutorial per le associazioni Python dinamiche → 3 settimane → Implementare tutorial per le specifiche ROOT
Risultati finali e linee guida per il successo: sunzione della documentazione dell'utente unificata senza lacune Documentazione dell'utente completamente aggiornata per riflettere le funzionalità più recenti, ad esempio nuove classi derivate Tutorial tramite blocchi note Jupyter