Progetto CERN-HSF

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:
Ariadne
Nome progetto:
Rucio - Modernizza (ristruttura e riscrivi) la documentazione di Rucio
Durata del progetto:
Durata standard (3 mesi)

Project description

Riassunto: Il framework Rucio è stato sviluppato con l'obiettivo di gestire e organizzare grandi volumi di dati scientifici distribuiti geograficamente in data center eterogenei. Offrendo funzionalità come il recupero distribuito dei dati e la replica adattiva, il framework è altamente scalabile, modulare ed estensibile. I consumatori della documentazione di un servizio di questo tipo provenivano da background diversi e devono soddisfare requisiti diversi al momento dell'accesso. Una buona documentazione per un servizio di questo tipo dovrebbe pertanto semplificarne l'adozione e l'utilizzo per gli utenti finali, oltre a essere un riferimento per i problemi comuni e la relativa risoluzione dei problemi.

In assenza di tale documentazione, ci sarebbero notevoli ostacoli all'utilizzo efficiente ed efficace. Questo potrebbe comportare un aumento dei costi di assistenza e un rischio per la reputazione dell'identità aziendale del prodotto. La documentazione è, dopotutto, una modalità di comunicazione. Garantire che la comunicazione sia incapsulata in un framework gestibile e accessibile pur rimanendo pertinente con un controllo delle versioni appropriato significa quindi garantire che stiamo comunicando per avere successo.

Al momento della stesura di questo documento, il framework Rucio è stato utilizzato per soddisfare i requisiti di alta energia degli esperimenti ATLAS e CMS presso l'LHC. Viene inoltre utilizzato per supportare le esigenze di diverse comunità scientifiche oltre all'LHC, come l'astrofisica, rendendo quindi necessario che la documentazione sia la più pertinente e accessibile possibile. Con l'aiuto di questo progetto, il CERN vuole consentire agli utenti finali di Rucio di avere un'esperienza senza soluzione di continuità utilizzando il framework, fornendo una visualizzazione centralizzata per accedere a tutta la documentazione pertinente.

Stato attuale: ad oggi la documentazione per gli utenti è distribuita in diversi luoghi ed è disponibile in più formati, inclusi articoli scientifici, readthedocs.io con codice sorgente, Google Drive, GitHub, DockerHub o Wiki. Diverse fonti introducono problemi relativi al monitoraggio delle versioni e alla correttezza della documentazione. Inoltre, un modello decentralizzato di documentazione pone notevoli ostacoli nella navigazione e nella visualizzazione delle informazioni pertinenti per un determinato caso d'uso. Soprattutto nel caso dei wiki, le informazioni fornite per un determinato esperimento potrebbero essere applicabili anche ad altre istanze che risiedono nella stessa fonte o in altre fonti. Tuttavia, a causa della mancanza di consolidamento e di collegamenti appropriati, queste informazioni rimangono inattive e, potenzialmente, sottoutilizzate.

Perché la documentazione utente proposta rappresenta un miglioramento rispetto a quella attuale? Dato il problema multiforme, il modello proposto di seguito elimina gli ostacoli relativi a navigazione, controllo delle versioni, monitoraggio e visualizzazione della documentazione, come descritto di seguito:

La ristrutturazione della documentazione mira a semplificare gli sforzi dedicati alla navigazione per un utente finale. Non è necessario che vada giù nella tana del coniglio mentre cerca informazioni, perché verrebbero categorizzate/etichettate per semplicità. Dal punto di vista amministrativo, il controllo delle versioni e il monitoraggio sarebbero semplificati poiché la ristrutturazione offrirebbe la libertà di classificare in base ai requisiti. Centralizzare tutta la documentazione ristrutturata serve a garantire che tutte le informazioni siano visibili all'utente senza dover fare riferimento a più fonti.

Analisi: dopo aver letto il riepilogo dei requisiti e aver parlato con il team di tutoraggio, le mie detrazioni dello stato attuale della documentazione di Rucio sono le seguenti:

Esistono sei fonti principali di documentazione: - Link di Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Readthedocs alimentato da Sphinx con codice sorgente Link al codice: https://github.com/rucio/rucio Link a ReadtheDocs: https://rucio.readthedocs.io/en/latest/

  • Link DockerHub: https://hub.docker.com/u/rucio

  • Link GitHub: https://github.com/rucio/rucio

  • Link Wiki: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing

  • Articoli scientifici Link: https://arxiv.org/abs/1902.09857

La documentazione di queste origini è in diversi formati. Ad esempio, Google Drive dispone della documentazione sotto forma di Presentazioni e Documenti, GitHub ha file principalmente nel linguaggio di markup reStructuredText e così via. La mancanza di controllo delle versioni e monitoraggio porta alla pubblicazione di informazioni ridondanti da più fonti. Non c'è uniformità nell'etichettatura/classificazione delle informazioni. Pertanto, è necessario avere esperienza e competenza precedenti nella ricerca.

Data la miriade di formati e fonti, ci si aspetta di riorganizzare le informazioni e di centralizzarle utilizzando mkdocs. Per migliorare la mia comprensione degli strumenti, ho effettuato ricerche e acquisito familiarità con il loro utilizzo.

Verdetto: la documentazione esistente non è strutturata e sparsa senza collegamenti appropriati. Manca inoltre la centralizzazione e l'uniformità della formattazione. Di conseguenza, gli utenti devono dedicare ulteriori energie alle ricerche. Queste lacune introducono inoltre pressioni inutili su amministratori/gestori/lead e, di conseguenza, diventa difficile mantenere un approccio gestito dalla community per la manutenzione e l'aggiornamento della documentazione. L'esperienza degli utenti e dei collaboratori è notevolmente ridotta e ci sarebbe stata ripetuta

Struttura per la documentazione proposta: Dopo un'analisi approfondita dei requisiti, ho deciso di risolvere i principali punti deboli riorganizzando la documentazione.
Il modello ristrutturato viene mostrato sul modello allegato di seguito e viene classificato ogni documento nelle 7 categorie seguenti:

  • Informazioni
  • Per iniziare
  • Concetti
  • Interfacce Rucio
  • Attività
  • Tutorial
  • Competenza avanzata

Naturalmente, ci sono dei miglioramenti, come l'aggiunta di link su cui mi piacerebbe lavorare una volta completato il programma. Con oltre 1000 utenti attivi che accedono a 500 petabyte di dati su Rucio, la ristrutturazione proposta della sua documentazione dovrebbe essere in grado di ridurre notevolmente la necessità da parte degli utenti di ricorrere alla mailing list di assistenza. L'obiettivo sarebbe migliorare l'esperienza utente riducendo il numero di percentuali di clic e mostrando la documentazione tramite categorizzazione ed etichettatura. Tutto ciò che c'è da sapere dal punto di vista di utenti, operazioni e personale amministrativo sarà disponibile in un massimo di tre clic.

Link fittizio: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing

Obiettivi del progetto: - Analizzare ed eliminare le informazioni ridondanti disponibili da varie fonti, ovvero ogni informazione deve avere un'unica fonte attendibile. - Ristrutturare etichettando e categorizzando la documentazione esistente in diverse parti - Eseguire la migrazione della documentazione ristrutturata a una visualizzazione centralizzata basata su mkdocs - Riformattare/importare la documentazione che non è possibile migrare a causa di vincoli relativi al formato dei file - Configurare la modifica della documentazione guidata dalla community per garantire che eventuali lacune mancanti vengano colmate, in termini di collegamenti, aggiornamenti alle informazioni o correzione di errori.

Gli elementi essenziali per questo sistema sono già in atto, tuttavia il mio modello migliorerebbe rispetto a quello esistente definendo linee guida appropriate per il contributo e la governance con la documentazione appropriata. Inoltre, immagino di incorporare commissioni di progetto GitHub per il monitoraggio dei problemi e dell'integrità complessiva del progetto.

Sequenza temporale: - Prima del 16 agosto --> Familiarizza con le versioni attuali della documentazione e Rucio --> Impara nuove tecniche e competenze di scrittura tecnica che saranno utili durante il periodo di validità del progetto --> Contribuisci agli eventuali problemi di documentazione segnalati su GitHub

  • Legame con la comunità (17 agosto - 13 settembre) --> Imposta un canale di comunicazione e il tempo per tenere conto della differenza di fuso orario (Pune è in anticipo di 3 ore e 30 minuti) --> Principali punti deboli da identificare per il perfezionamento degli obiettivi --> Scopri di più sulla community, sull'organizzazione e sul framework intervenendo in conversazioni. --> Valutazione della struttura di documentazione proposta con mentori e altri membri chiave dell'organizzazione per la fattibilità e la fattibilità dell'implementazione. --> Finalizzazione delle funzionalità proposte ed eventuali altre modifiche da apportare alla documentazione esistente.

  • Periodo di documentazione (14 settembre - 30 novembre) Sulla base del formato proposto che ho formulato qui, ho fornito una suddivisione dei principali traguardi che intendo raggiungere durante il periodo di documentazione.

--> Traguardo n. 1: classificazione ed etichettatura ETC: 28 settembre 2020 L'assimilazione e l'etichettatura della documentazione disponibile semplificherebbe notevolmente il processo di ristrutturazione e potatura.

--> Traguardo n. 2: Analisi, potatura e ristrutturazione ETC: 19 ottobre 2020 La documentazione classificata durante il traguardo 1 verrà analizzata per individuare duplicati e fonti di informazioni ridondanti. Come indicato nelle informazioni del progetto, puntiamo a un'unica fonte attendibile per tutte le informazioni disponibili.

--> Traguardo n. 3: Centralizzazione e riformattazione: ETC: 9 novembre 2020 Una volta che la documentazione è stata eliminata e ristrutturata correttamente, volevo riformattarla. A causa delle varie origini, i formati sono diversi e devono prima essere trasformati in un formato appropriato. Una volta eseguita questa operazione, il processo di centralizzazione diventerà più semplice.

--> Traguardo n. 4: configurazione dei riquadri di monitoraggio + documentazione sulla governance e sui contributi ETC: 23 novembre 2020 Questa fase serve a garantire che, dopo il completamento del progetto, la documentazione continui a rimanere aggiornata. La definizione di linee guida e l'istituzione di commissioni di progetto alleggeriscono il compito dei membri amministrativi di sollecitare i contributi della comunità e di monitorarli in modo efficace.

--> Valutazione del progetto (30 novembre - 5 dicembre) Invia una relazione sul progetto e la valutazione dei miei mentori Scrivi e invia un resoconto della mia esperienza di partecipante alla stagione di Documenti.

Perché questo progetto? Ritengo che l'integrazione del codice con una documentazione ben scritta e sottoposta a controllo delle versioni sia l'unico modo per consentirne un'ulteriore adozione e un migliore utilizzo. Personalmente, sono stato affascinato dal modo in cui il CERN ha sperimentato ricerche all'avanguardia in diverse aree della fisica. Data la portata delle informazioni elaborate, trasferite e generate durante questi esperimenti, mi ha sempre incuriosito il modo in cui i dati venivano gestiti per riferimento e come utilizzo futuro all'interno dell'organizzazione. Sarebbe un onore contribuire al miglioramento della documentazione per un framework che è stato alla base di alcune straordinarie ricerche e scoperte scientifiche.

Perché sono la persona giusta per questo progetto? Oltre a soddisfare i prerequisiti, sono sicura di essere la persona giusta per questo progetto poiché:

Sto già lavorando alla modifica della documentazione esistente per Kubernetes. Questi contributi mi hanno permesso di essere arruolato come ombra dei documenti di rilascio per il ciclo di rilascio di Kubernetes 1.19, in cui contribuisco alla manutenzione e all'upgrade efficaci della documentazione per le nuove funzionalità che vengono aggiunte durante il rilascio. Credo che una buona documentazione sia la spina dorsale per un ottimo prodotto/servizio. Che si tratti di informazioni procedurali o tecniche, le informazioni ben scritte, concise e facilmente accessibili costituirebbero un impulso per l'adozione e il miglioramento dell'utilizzo. Avendo lavorato con sistemi distribuiti basati sui dati per tutta la mia carriera, credo di essere nella posizione migliore per comprendere le complessità dei requisiti in merito alla documentazione di questi sistemi. Essendo io stesso un utente finale, conosco le insidie legate alla documentazione scritta male o incorretta e farò attenzione a tenerle in considerazione durante la ristrutturazione.