Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- CERN-HSF
- Redattore tecnico:
- Mario
- Nome del progetto:
- CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
CERN-HSF - Documentazione di ROOT per l'adozione da parte del pubblico in generale, binding dinamici di Python e tutorial Mentor: Olivier Couet, Axel Naumann
Riassunto: La documentazione è essenziale per un'adozione efficace ed efficiente del software da parte degli utenti. Una documentazione utente chiara, accurata e completa facilita la conoscenza del software da parte degli utenti mentre si impegnano a raggiungere i loro obiettivi. Di conseguenza, gli esempi e i tutorial espliciti rappresentano strumenti efficaci con cui gli utenti possono imparare rapidamente.
Mentre esaminiamo l'utilizzo di ROOT da parte di fisici, ricercatori e sviluppatori nell'ambito dell'analisi e della visualizzazione dei dati per la fisica, riconosciamo i vantaggi di una documentazione aggiornata e facile da usare. In particolare, data l'ampiezza del codice sorgente e la sua crescita, il sistema di documentazione può trarre vantaggio dall'evoluzione parallela per concedere agli utenti la possibilità di massimizzare tutto ciò che ROOT ha da offrire.
Riepilogo e analisi della documentazione attuale Al momento, la documentazione per gli utenti offre una guida che consente ai fisici di adottare ROOT più facilmente rispetto a un pubblico generale. Inoltre, in determinati argomenti, come le associazioni dinamiche di Python, potrebbero essere apportati miglioramenti per una documentazione più completa e chiara. Analogamente, il nuovo formato di dati RNTuple non contiene le 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 essere identificare le lacune di conoscenza tra i ricercatori specializzati e un pubblico generale, creare la documentazione per colmare questa lacuna, scrivere una documentazione più dettagliata delle associazioni dinamiche di Python, implementare "tutorial per l'analisi moderna" per ROOT 7 e creare specifiche tecniche dettagliate per RNTuple. Durante questo processo, la documentazione potrebbe incorporare blocchi note Jupyter in modo che strumenti di apprendimento tangibili e interattivi possano aiutare gli utenti.
Tempistiche: si stima che le fasi del progetto siano: identificare le lacune di conoscenza tra i ricercatori specializzati e un pubblico generale (durante la lettura della documentazione e del codice sorgente attuali) → 1-2 settimane creare e riorganizzare la documentazione per colmare questa lacuna → 3 settimane scrivere una documentazione più dettagliata delle associazioni dinamiche di Python → 3 settimane implementare tutorial per le associazioni dinamiche di Python → 3 settimane implementare tutorial per ROOT 7 → 4 settimane creare specifiche tecniche dettagliate per RNTuple → 3 settimane verificare il completamento degli obiettivi del progetto → 1 settimana
Risultati e linee guida per il successo: Documentazione utente unificata singola senza lacune Documentazione utente completamente aggiornata in base alle funzionalità più recenti, ad esempio nuove classi derivate Tutorial tramite Jupyter Notebook