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:
- SabitaR
- Nome progetto:
- Ristrutturazione e ottimizzazione della documentazione di Allpix Squared
- Durata del progetto:
- Durata standard (3 mesi)
Project description
PANORAMICA Ho scelto il progetto Allpix Squared del CERN-HSF per due motivi principali:
Sviluppo delle competenze: la documentazione esistente di questo progetto è completa e integra vari formati di contenuti. Controllare e ristrutturare questa ampia suite di documenti mi aiuterà a perfezionare la mia architettura delle informazioni e le mie capacità di scrittura. Inoltre, il dominio del progetto (fisica delle particelle) è nuovo per me. Mi sfida ad affinare le mie capacità di interazione con gli sviluppatori. Ritengo che i Technical Writer possano elaborare gli input degli sviluppatori e presentare contenuti utili per utenti di qualsiasi livello, SE eseguiamo le nostre ricerche di base richieste e poniamo le domande giuste. Questo progetto mi consentirà di testare questa teoria.
Competenze tecniche: Questo progetto richiede Hugo, uno strumento che rientra nelle mie attività di apprendimento. Non vedo l'ora di imparare il flusso di lavoro di LaTeX-Markdown-Hugo-GitLab-CI.
Durante la fase di esplorazione del Technical Writer, ho interagito brevemente con i mentori del progetto e ho acquisito familiarità con la struttura della suite di documenti esistente. Ho anche creato un sito web demo (https://ap2-demo.netlify.app/) per testare se riesco a configurare correttamente Hugo e Docsy sul mio computer Windows. Ho eseguito il deployment del sito web su Netlify, ma non sulle pagine Gitlab. Per fare in modo che questo progetto mantenga l'attuale flusso di lavoro di deployment, troverò un modo per eseguire il deployment del tema Hugo Docsy nelle pagine Gitlab.
RISULTATI PREVISTI DEL PROGETTO - Sito web di progetto semplificato che integra documentazione, riferimenti sul codice, tutorial e notizie. - Un manuale dell'utente riorganizzato e rivisto in modo da separare i contenuti destinati a utenti e sviluppatori e includere informazioni mancanti in precedenza. - Un flusso di lavoro dei tutorial a partire da esempi disponibili di documentazione illustrativa, domande frequenti e problemi comuni.
STRUMENTI PER IL PROGETTO L'attuale documentazione di Allpix Squared utilizza LaTeX, Doxygen, pandoc e Hugo, oltre a GitLab e Gitlab CI. I mentori del progetto e io abbiamo parlato della possibilità di spostare i contenuti da LaTeX a Markdown con i plug-in di MathJax. Se ho successo, il flusso di lavoro del documento coinvolgerà Hugo, Markdown, Doxygen, git e Gitlab CI. Per mantenere i tutorial sullo stesso sito web/piattaforma, userò Hugo e Markdown. Mi incuriosisce sapere se è possibile utilizzare Codelabs-as-a-Tool (ClaaT) per i tutorial. A luglio spero di testare il flusso di lavoro di ClaaT-Hugo e di discuterne con i mentori, se selezionati.
DURATA DEL PROGETTO Chiedo di completare il progetto Allpix Squared entro il periodo standard di tre mesi (14 settembre 2020 - 30 novembre 2020), durante il quale ci dedicherò circa 15 ore a settimana. Questi orari includeranno riunioni con i mentori e le relative email, se necessario. Rispetterò anche le tempistiche di GSoD per i legami con la comunità e per la finalizzazione del progetto.
ATTIVITÀ DEL PROGETTO Ecco come intendo implementare gli aggiornamenti proposti per la suite di documenti esistente di Allpix Squared: 1. Effettua ricerche, discuti ed esplora le opzioni (17 agosto - 13 settembre 2020): - Comprendere i requisiti del progetto - Installare il software Allpix Squared per identificare eventuali informazioni mancanti nei documenti attuali. - Richiedere le credenziali necessarie. - Crea flussi di lavoro utente per diversi utenti di Allpix Squared - Classifica i contenuti in base al ruolo utente - Verifica le implicazioni della conversione dei file LaTeX in Markdown - Consolida i repository di codice sorgente o scopri come lavorare con più repository Git - Bonus: testa CLaaT come opzione per i tutorial - Bonus: crea una guida di stile rapida/riferimento sulle fasi di Shortcode per aiutare i collaboratori della community a mantenere i documenti
Ristruttura, rivedi e migliora i contenuti (14 settembre - 19 ottobre 2020): due attività a settimana, circa 5-7 ore per attività. Questa sequenza temporale include una settimana di margine per la gestione di ritardi o problemi imprevisti.
- Esamina i contenuti esistenti e le classificazioni degli utenti tenendo presente i flussi di lavoro degli utenti
- Delinea e testa il flusso di lavoro dei contenuti ristrutturati per i diversi utenti
- Fonte e miglioramento dei contenuti mancanti
- Converti file LaTeX in Markdown
- Finalizza il sommario della guida dell'utente e della guida per gli sviluppatori
- Generare PDF delle guide per l'utente e per gli sviluppatori
- Extra: struttura i contenuti dei tutorial sulla base di esempi e problemi
- Bonus: imposta un flusso di lavoro del tutorial per gli esempi di istruzioni Sequenza temporale: 5 settimane (fase di sviluppo del documento)
Crea il sito web (19 ottobre - 30 novembre 2020): 1-2 attività a settimana, circa 5-7 ore per attività. Questa sequenza temporale include una settimana di buffer per risolvere i problemi e perfezionare l'output finale.
- Comprendere e testare il flusso di lavoro di pubblicazione
- Crea la struttura di un sito web utilizzando Hugo e Docsy
- Testa come mantenere l'attuale deployment automatico e il flusso di lavoro utilizzando Docsy
- Estrai contenuti da Doxygen
- Sviluppa manuali dell'utente, guida per gli sviluppatori e tutorial dai contenuti LaTex o Markdown
- Finalizza l'aspetto del sito web del progetto (logo, colori, modello, layout, link, usabilità e CI/CD Gitlab) Tempistiche: 6 settimane (fase di sviluppo del documento)