Progetto CERN-HSF

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.

Riepilogo del progetto

Organizzazione open source:
CERN-HSF
Redattore tecnico:
Ariadne
Nome del progetto:
Rucio: modernizzare (ristrutturare e riscrivere) la documentazione di Rucio
Durata del progetto:
Durata standard (3 mesi)

Project description

Abstract: Il framework Rucio è stato sviluppato allo scopo di gestire e organizzare grandi volumi di dati scientifici distribuiti geograficamente in data center eterogenei. Offrendo funzionalità come il recupero dei dati distribuiti e la replica adattiva, il framework è estremamente scalabile, modulare ed estensibile. I consumatori della documentazione per un servizio di questo tipo provengono da background diversi e hanno requisiti diversi per l'accesso. Una buona documentazione per un servizio di questo tipo dovrebbe quindi semplificarne l'adozione e l'utilizzo per gli utenti finali, oltre a essere un riferimento per i problemi e la risoluzione dei problemi comuni.

In assenza di tale documentazione, l'utilizzo efficiente ed efficace potrebbe comportare notevoli ostacoli. Ciò potrebbe potenzialmente portare a un aumento dei costi di assistenza e comportare un rischio per la reputazione dell'identità aziendale del prodotto. Dopo tutto, la documentazione è una modalità di comunicazione. Assicurarsi che la comunicazione sia incapsulata in un framework gestibile e accessibile, rimanendo pertinente con una versione appropriata, è quindi un modo per garantire il successo della comunicazione.

Al momento della stesura di questo articolo, il framework Rucio è stato utilizzato per soddisfare i requisiti di alta energia degli esperimenti ATLAS e CMS all'LHC. Viene inoltre utilizzato per supportare le esigenze di diverse comunità scientifiche, che vanno oltre l'LHC, come l'astrofisica, rendendo così necessaria la documentazione più pertinente e accessibile. Con l'aiuto di questo progetto, il CERN vuole consentire agli utenti finali di Rucio di avere un'esperienza senza interruzioni utilizzando il framework fornendo una vista 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, tra cui articoli scientifici, readthedocs.io con codice sorgente, Google Drive, GitHub, DockerHub o wiki. La presenza di più fonti introduce problemi con il monitoraggio delle versioni e la correttezza della documentazione. Inoltre, un modello decentralizzato di documentazione pone ostacoli significativi alla navigazione e alla visualizzazione delle informazioni pertinenti per un determinato caso d'uso. Soprattutto nel caso delle wiki, le informazioni fornite per un determinato esperimento potrebbero essere applicabili anche ad altre istanze presenti nelle stesse/altre origini. Tuttavia, a causa della mancanza di consolidamento e di collegamenti appropriati, queste informazioni rimangono inattive e, potenzialmente, sottoutilizzate.

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

La ristrutturazione della documentazione mira a semplificare le operazioni di navigazione per un utente finale. Non ha bisogno di andare in buca di conigli durante la ricerca di informazioni, poiché per semplicità vengono categorizzate/etichettate. 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. La centralizzazione di 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 brief dei requisiti e aver parlato con il team di tutoraggio, le mie deduzioni sullo stato attuale della documentazione di Rucio sono le seguenti:

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

  • Readthedocs basato su Sphinx con codice sorgente nel codice Link al codice: https://github.com/rucio/rucio Link a ReadtheDocs: https://rucio.readthedocs.io/it/latest/

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

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

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

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

La documentazione di queste origini è in formati diversi. Ad esempio, Google Drive ha la documentazione sotto forma di Presentazioni e Documenti, GitHub ha file principalmente nel linguaggio di markup reStructuredText e così via. La mancanza di versionamento e monitoraggio porta alla pubblicazione di informazioni ridondanti in più origini. Non esiste uniformità nell'etichettatura/classificazione delle informazioni. Pertanto, durante la ricerca sono richieste esperienza e competenze pregresse.

Data la miriade di formati e origini, si prevede di ristrutturare le informazioni e centralizzarle utilizzando mkdocs. Per comprendere meglio gli strumenti, ho svolto ricerche e mi sono familiarizzata con il loro utilizzo.

Giudizio: la documentazione esistente è non strutturata e dispersa senza collegamenti appropriati. Manca inoltre la centralizzazione e l'uniformità nella formattazione. Di conseguenza, gli utenti devono fare uno sforzo maggiore per le ricerche. Queste lacune introducono anche una pressione non necessaria su amministratori/gestori/responsabili, per cui diventa difficile mantenere un approccio basato sulla community per la manutenzione e l'aggiornamento della documentazione. L'esperienza degli utenti e dei collaboratori è notevolmente peggiorata e si verificheranno ripetutamente

Struttura della documentazione proposta: Dopo un'analisi approfondita dei requisiti, ho deciso di risolvere i principali problemi tramite un modello di documentazione ristrutturato.
Il modello ristrutturato è mostrato nel mockup allegato di seguito e classifica ogni documento nelle sette categorie riportate di seguito:

  • Informazioni
  • Per iniziare
  • Concetti
  • Interfacce Rucio
  • Tasks
  • Tutorial
  • Know-how avanzato

Naturalmente, ci sono miglioramenti, come l'aggiunta di link, che vorrei implementare dopo il completamento di questo programma. Con oltre 1000 utenti attivi che accedono a 500 petabyte di dati su Rucio, la ristrutturazione proposta della documentazione dovrebbe essere in grado di ridurre notevolmente la necessità da parte degli utenti di ricorrere alla mailing list di assistenza. L'obiettivo è migliorare l'esperienza utente riducendo il numero di tassi di clic e mostrando facilmente la documentazione tramite categorizzazione ed etichettatura. Tutto ciò che è necessario sapere dal punto di vista del personale utente/operativo/amministrativo sarà disponibile in massimo 3 clic.

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

Scopi del progetto: - Analizza e rimuovi le informazioni ridondanti disponibili da varie fonti. Ad esempio, ogni informazione deve avere una sola fonte attendibile. - Esegui la ristrutturazione etichettando e suddividendo la documentazione esistente in parti diverse - Esegui la migrazione della documentazione ristrutturata a una visualizzazione centralizzata basata su mkdocs - Esegui il riformattazione/l'importazione della documentazione di cui non è possibile eseguire la migrazione a causa di vincoli relativi al formato dei file - Configura la modifica della documentazione basata sulla community per assicurarti che eventuali lacune mancanti vengano colmate, in termini di link, aggiornamenti delle informazioni o correzione di errori.

Le basi di questo sistema sono già in atto, ma il mio modello migliorerebbe il sistema esistente stabilendo linee guida adeguate per i contributi e la governance con la documentazione appropriata. Inoltre, prevedi di incorporare le bacheche dei progetti GitHub per monitorare i problemi e l'integrità generale del progetto.

Tempistiche: - Prima del 16 agosto --> Acquisire familiarità con le versioni attuali della documentazione e di Rucio --> Acquisire nuove tecniche e competenze di scrittura tecnica che saranno utili durante il periodo del progetto --> Contribuire a risolvere eventuali problemi di documentazione segnalati su GitHub

  • Coesione della community (17 agosto - 13 settembre) --> Configura un canale di comunicazione e un orario in base alla differenza di fuso orario (Pune è 3 ore e 30 minuti avanti) --> Identificare i principali problemi da risolvere per perfezionare gli obiettivi --> Scopri di più sulla community, sull'organizzazione e sul framework partecipando alle conversazioni. --> Valutazione della struttura della documentazione proposta con i mentor e altri membri chiave dell'organizzazione per verificare la fattibilità e la fattibilità dell'implementazione. --> Finalizzazione delle funzionalità proposte e di eventuali altre modifiche che potrebbero essere necessarie alla documentazione esistente.

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

--> Traguardo 1: classificazione ed etichettatura Data di fine: 28 settembre 2020 L'assimilazione della documentazione disponibile e la relativa etichettatura semplificherebbero notevolmente la procedura di ristrutturazione e potatura.

--> Traguardo 2: analisi, potatura e ristrutturazione Data di fine: 19 ottobre 2020 La documentazione classificata durante il traguardo 1 verrà analizzata per rilevare duplicati e fonti di informazioni ridondanti. Come indicato nelle informazioni del progetto, abbiamo scelto come target una singola fonte attendibile per tutte le informazioni disponibili.

--> Traguardo 3: centralizzazione e riformattazione: Data di fine prevista: 9 novembre 2020 Una volta ripulita e ristrutturata correttamente la documentazione, mi concentrerò prima sulla riformattazione. A causa delle varie origini, i formati sono diversi e devono prima essere trasformati in un formato appropriato. Una volta completata questa operazione, la procedura di centralizzazione sarà semplificata.

--> Traguardo 4: configurazione di schede di monitoraggio e documentazione su governance/contributi ETC: 23 novembre 2020 Questa fase serve a garantire che, una volta completato il progetto, la documentazione continui a rimanere aggiornata. Stabilire linee guida e configurare bacheche dei progetti alleggerirà il carico dei membri amministrativi per sollecitare i contributi della community e monitorarli in modo efficace.

--> Valutazione del progetto (30 novembre - 5 dicembre) Invio di un report sul progetto e valutazione dei miei mentori Scrivere e inviare un report sulla mia esperienza come partecipante a Season of Docs.

Perché questo progetto? Ho sempre pensato che integrare il codice con una documentazione ben scritta e con versioni sia l'unico modo per favorire un'ulteriore adozione e un utilizzo migliore. Personalmente, mi ha affascinato il modo in cui il CERN ha aperto la strada alla ricerca all'avanguardia in diversi campi della fisica. Data la scala delle informazioni elaborate, trasferite e generate durante questi esperimenti, mi ha sempre affascinato il modo in cui i dati venivano gestiti per riferimento e utilizzo futuro all'interno dell'organizzazione. Sarebbe un onore contribuire al miglioramento della documentazione per un quadro che ha contribuito ad 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 perché:

Sto già lavorando alla modifica della documentazione esistente per Kubernetes. In virtù di questi contributi, sono stato inserito come utente secondario della documentazione di release per il ciclo di release di Kubernetes 1.19, in cui contribuisco a mantenere e aggiornare efficacemente la documentazione per le nuove funzionalità aggiunte durante le release. Credo che una buona documentazione sia la base di un prodotto/servizio eccezionale. Che si tratti di informazioni procedurali o tecniche, informazioni ben scritte, concise e facilmente accessibili stimolerebbero l'adozione e un migliore utilizzo. Avendo lavorato con sistemi distribuiti basati sui dati durante tutta la mia carriera, credo di essere nella posizione migliore per comprendere le complessità dei requisiti relativi alla documentazione per questi sistemi. Essendo io stesso un utente finale, conosco i rischi della documentazione scritta male/errata e cercherò di tenerli in considerazione durante la ristrutturazione.