Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo progetto
- Organizzazione open source:
- CERN-HSF
- Redattore tecnico:
- SabitaR
- Nome del progetto:
- Ristrutturazione e semplificazione 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 diversi formati di contenuti. Il controllo e la ristrutturazione di questa ampia suite di documenti mi aiuteranno a perfezionare l'architettura delle informazioni e le mie capacità di scrittura. Inoltre, il dominio del progetto (fisica delle particelle) è nuovo per me. Mi spinge a perfezionare le mie competenze di interazione con gli sviluppatori. Credo che i redattori tecnici possano elaborare i dati degli sviluppatori e presentare contenuti utili per qualsiasi livello di utente, SE effettuiamo la ricerca di base necessaria e poniamo le domande giuste. Questo progetto mi consentirà di testare questa teoria.
Know-how tecnico: Questo progetto richiede Hugo, uno strumento che è in cima alla mia lista di cose da imparare. Non vedo l'ora di imparare il flusso di lavoro LaTeX-Markdown-Hugo-GitLab-CI.
Durante la fase di esplorazione del documento tecnico, ho interagito brevemente con i mentor del progetto e mi sono familiarizzato con la struttura della suite di documenti esistente. Ho anche creato un sito web di prova (https://ap2-demo.netlify.app/) per verificare se riesco a configurare Hugo e Docsy correttamente sul mio computer Windows. Ho potuto eseguire il deployment del sito web su Netlify, ma non sulle Pagine Gitlab. Per mantenere l'attuale flusso di lavoro di deployment di questo progetto, troverò un modo per eseguire il deployment del tema Hugo Docsy in Gitlab Pages.
RISULTATI DEL PROGETTO PREVISTI - Un sito web del progetto semplificato che integra documentazione, riferimenti al codice, tutorial e notizie. - Un manuale dell'utente ristrutturato e rivisto che separa i contenuti destinati a utenti e sviluppatori e include informazioni precedentemente mancanti. - Un flusso di lavoro di tutorial basato su esempi disponibili di documentazione di procedure, domande frequenti e problemi comuni.
STRUMENTI DEL PROGETTO La documentazione attuale di Allpix Squared utilizza LaTeX, Doxygen, pandoc e Hugo, oltre a GitLab e Gitlab CI. I mentor del progetto e io abbiamo parlato della possibilità di spostare i contenuti da LaTeX a Markdown con i plug-in MathJax. Se riesco, il flusso di lavoro della documentazione coinvolgerà Hugo, Markdown, Doxygen, git e Gitlab CI. Per mantenere i tutorial all'interno della stessa piattaforma/sito web, utilizzerò Hugo e Markdown. Mi interessa la fattibilità dell'utilizzo di Codelab come strumento (ClaaT) per i tutorial. A luglio spero di testare il flusso di lavoro ClaaT-Hugo e di discuterne con i mentor, se selezionati.
DURATA DEL PROGETTO Vorrei completare il progetto Allpix Squared entro il periodo standard di tre mesi (14 settembre 2020 - 30 novembre 2020), durante il quale lavorerò al progetto per circa 15 ore a settimana. Queste ore includeranno le riunioni con il mentore e le email correlate, se necessario. Rispetterò anche le tempistiche del GSoD per il coinvolgimento della community e la finalizzazione del progetto.
TASK DEL PROGETTO Ecco come intendo implementare gli aggiornamenti proposti alla suite di documenti Allpix Squared esistente: 1. Ricerca, discussione ed esplorazione delle opzioni (17 agosto - 13 settembre 2020): - Comprendi i requisiti del progetto - Installa il software Allpix Squared per identificare eventuali informazioni mancanti nei documenti attuali. - Richiedere le credenziali necessarie. - Creare flussi di lavoro per utenti diversi di Allpix Squared - Classificare i contenuti in base al ruolo dell'utente - Controllare le implicazioni della conversione dei file LaTeX in Markdown - Consolidare i repository di origine o capire come utilizzare più repository Git - Bonus: testare CLaaT come opzione per i tutorial - Bonus: creare una breve guida di stile/un riferimento agli shortcode per aiutare i collaboratori a gestire i documenti Tempistiche: fase di creazione di legami con la community
Ristrutturazione, revisione e miglioramento dei contenuti (14 settembre - 19 ottobre 2020): Due attività a settimana, circa 5-7 ore per attività. Questa sequenza temporale include una settimana buffer per gestire ritardi o problemi imprevisti.
- Rivedi i contenuti e le classificazioni degli utenti esistenti tenendo presente i flussi di lavoro degli utenti
- Definire e testare il flusso di lavoro dei contenuti ristrutturati per utenti diversi
- Recuperare e migliorare i contenuti mancanti
- Converti i file LaTeX in Markdown
- Definire il sommario della guida dell'utente e della guida per gli sviluppatori
- Genera PDF delle guide per l'utente e per gli sviluppatori
- Extra: strutturare i contenuti dei tutorial a partire da esempi e problemi
- Extra: configura un flusso di lavoro per i tutorial per esempi di procedure Tempistiche: 5 settimane (fase di sviluppo della documentazione)
Crea il sito web (19 ottobre - 30 novembre 2020): 1-2 attività a settimana, circa 5-7 ore per attività. Questa tempistica include una settimana di tempo per risolvere i problemi e perfezionare l'output finale.
- Comprendere e testare il flusso di lavoro di pubblicazione
- Creare la struttura di un sito web utilizzando Hugo e Docsy
- Testa come mantenere l'attuale implementazione automatica e il flusso di lavoro utilizzando Documentiy
- Estrai contenuti da Doxygen
- Sviluppare manuali dell'utente, guide per gli sviluppatori e tutorial da contenuti LaTex o Markdown
- Definire l'aspetto del sito web del progetto (logo, colori, modello, layout, link, usabilità e CI/CD di Gitlab) Tempistiche: 6 settimane (fase di sviluppo della documentazione)