Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.
Riepilogo del progetto
- Organizzazione open source:
- INCF
- Technical writer:
- hq
- Nome progetto:
- Documenti di formazione LRIS per la neuroscienze riproducibili aperte
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
I. Riassunto
Il sistema Longitudinal Online Research and Imaging (LORIS) è una piattaforma di gestione di progetti rivolta al web per la ricerca di neuroimaging che supporta diverse iniziative di Open Science. La documentazione gioca un ruolo importante per LORIS. In particolare, la documentazione aiuta gli utenti e gli sviluppatori di LORIS a comprendere i dettagli del software in modo che possano utilizzare meglio la piattaforma o contribuire allo sviluppo del software. Nel frattempo, dovrebbe essere aggiornata anche la documentazione del LORIS. Questo progetto mira ad aiutare LORIS a migliorare la propria documentazione.
II. Stato attuale
Attualmente LORIS utilizza il Wiki di GitHub, Leggi i documenti e il sito web LORIS.ca per ospitare tutta la documentazione. Nello specifico, il Wiki di LORIS su GitHub ospita la più grande quantità di documentazione LORIS, mentre ulteriori tutorial, presentazioni, guide per l'utente e procedure dettagliate di LORIS sono ospitati su varie piattaforme . L'attuale documentazione di LORIS fornisce guide per gli sviluppatori e gli utenti LORIS, ma potrebbe trarre vantaggio da un ulteriore sviluppo e organizzazione, in particolare negli aggiornamenti della documentazione e nei miglioramenti dei dettagli tecnici.
III. Vantaggi per la community
Migliorando i documenti di formazione LORIS per la neuroscienze riproducibili aperte, ricercatori e sviluppatori potrebbero trarre vantaggio da uno strumento più facile da usare, per migliorare la raccolta dei dati nei loro studi. In particolare, il progetto potrebbe aggiornare e migliorare la documentazione di installazione/configurazione di LORIS, nonché materiali per gli utenti finali che forniscono formazione ai nuovi utenti. Inoltre, il progetto punterà alla migrazione e all'aggiornamento della documentazione dal wiki GitHub di LORIS in Read the Docs. Nel frattempo, il progetto potrebbe fornire un diagramma di database per comunicare le relazioni tra i dati e migliorare la visualizzazione dell'architettura. Infine, questo progetto ha l'obiettivo di aggiornare e migliorare i contenuti che introducono le persone a LORIS, il suo contesto scientifico aperto e i suoi casi d'uso.
IV. Punti di forza personali del progetto
Negli ultimi anni ho partecipato a diversi progetti tecnici grazie ai quali ho acquisito una solida esperienza in scrittura tecnica. In particolare, ero responsabile della scrittura di documenti in diversi progetti precedenti con il team e credo di avere sufficiente esperienza nell'uso di strumenti di scrittura tecnica come Read the Docs, Sphinx, Mkdocs, markdown, LaTeX ecc. Nel frattempo, la mia precedente esperienza di insegnamento nei corsi STEM ha migliorato anche le mie capacità di comunicazione tecnica. I documenti di formazione del LORIS per progetti di neuroscienza aperta e riproducibili con l'INCF sarebbero per me un'ottima opportunità per applicare le mie tecniche di scrittura tecnica a LORIS. Inoltre, sono molto interessato al campo del neuroimaging e ho cercato di trovare opportunità per applicare le mie conoscenze tecniche a questo campo. I documenti di formazione LORIS per progetti di neuroscienza aperta e riproducibili con l'INCF sarebbero un'esperienza preziosa per me.
V. Risultati finali
- Esegui la migrazione e aggiorna la documentazione LORIS attuale
- Esamina, aggiorna e migliora la documentazione di installazione/configurazione di LORIS e colma le lacune nei materiali per gli utenti finali fornendo formazione ai nuovi utenti
- Aiuta a generare un diagramma del database per comunicare le relazioni tra i dati (ad esempio, materia, visita di studio) e migliorare la visualizzazione dell'architettura
- Contribuisci ad aggiornare e migliorare la documentazione dell'API LORIS
- Contribuisci ad aggiornare e migliorare i contenuti che introducono le persone su LORIS, il suo contesto scientifico aperto e i suoi casi d'uso, includendo diversi formati multimediali
VI. Sequenza
Community Bonding (17 agosto - 13 settembre) a) Acquisire familiarità con il software LORIS e il flusso di lavoro del team. b) Esamina, aggiorna e migliora la documentazione di installazione/configurazione di LORIS.
Settimana 1 (14 settembre - 20 settembre) Aggiorna ed esegui la migrazione della documentazione LORIS dal wiki GitHub a Leggi la documentazione.
Settimana 2 (21 settembre - 27 settembre) a) Esamina i materiali attuali per gli utenti finali di LORIS. b) Iniziare a colmare le lacune nei materiali per gli utenti finali di LORIS, fornendo formazione ai nuovi utenti in base alla documentazione attuale.
Settimana 3 (28 settembre - 4 ottobre) Colma le lacune nei materiali per gli utenti finali LORIS fornendo formazione ai nuovi utenti.
Settimana 4 (5-11 ottobre) a) Comprensione dell'attuale architettura del database LORIS. b) Inizia a implementare il diagramma del database per la piattaforma LORIS.
Settimana 5 (12-18 ottobre) a) Completa l'attività di generazione del diagramma del database LORIS. b) Esamina l'API LORIS attuale e inizia a contribuire a migliorare la documentazione dell'API.
Settimana 6 (19 - 25 ottobre) Continua a lavorare al miglioramento della documentazione dell'API LORIS.
Settimana 7 (26 ottobre - 1° novembre) Termina il miglioramento nella documentazione dell'API LORIS.
Settimana 8 (2-8 novembre) Rivedi i contenuti attuali che introducono le persone su LORIS e inizia ad aggiornare e a migliorare il contesto della scienza aperta.
Settimana 9 (9-15 novembre) Termina gli aggiornamenti e i miglioramenti del contesto di scienze aperte nei contenuti dell'introduzione alle persone di LORIS.
Settimana 10 (16-22 novembre) Contribuisci ad aggiornare e migliorare parte dei casi d'uso nei contenuti che introducono le persone a LORIS.
Settimana 11 (23-29 novembre) Termina l'aggiornamento e il miglioramento di tutti i casi d'uso nei contenuti che introducono le persone a LORIS.
Finalizzazione del progetto (30 novembre - 5 dicembre) a) Ripulisci tutti i contributi alla documentazione che ho creato. b) Unisci tutte le richieste di pull create su GitHub e chiudi tutti i problemi che ho creato. c) Termina il mio report finale sul progetto e invia il report a Google.
VII. Risultati finali
Dopo la stagione dei documenti Google 2020, vorrei continuare a contribuire alla documentazione per LORIS. Nello specifico, vorrei discutere con gli sviluppatori LORIS della possibilità di continuare ad aggiornare e creare documentazione per le nuove release. Inoltre, vorrei dedicare più tempo a rivedere la documentazione che ho creato durante il mio progetto Google Season of Docs per controllare se c'è più spazio per migliorare. Infine, dato che ho un background di ingegneria pertinente, sono disponibile a contribuire ad altri aspetti del software LORIS in futuro, ad esempio lo sviluppo del software.