Progetto DIPY

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

Riepilogo del progetto

Organizzazione open source:

DIIP

Technical writer:

Areesha Tariq

Nome progetto:

Ristrutturazione di alto livello e attenzione sugli utenti finali

Durata del progetto:

Durata standard (3 mesi)

Project description

Sono un Software Engineer con competenze di scrittura tecnica. Ho più di 4 anni di esperienza nella creazione di documenti software, guide dell'utente, manuali e descrizioni di progetti di alta qualità. Vivo a Islamabad, Pakistan (fuso orario: UTC + 5). Attualmente, lavoro come tirocinante per il Sociale da Segreteria, che continuerà fino al 18 agosto. Ho partecipato a Google Season of Docs come Technical Writer nell'organizzazione OpenELIS Global. La documentazione originale era in francese, limitata e obsoleta, quindi ho creato un'ampia documentazione aggiornata per l'utente finale in inglese. Sono stato selezionato per il Sociale per il Sociale nell'organizzazione Perl & Raku da maggio ad agosto 2020 come sviluppatore backend del server Open Food Facts. Oltre allo sviluppo back-end, una delle attività principali di questo tirocinio è creare documentazione per i moduli e le funzioni in formato POD. L'anno scorso sono entrato nel mondo dell'open source, quando ho contribuito ad alcuni progetti open source e in seguito ho partecipato a Google Season of Docs. Quest'anno sono stato selezionato nel programma per il Sociale a supporto della diversità nel software open source e senza costi. Ho una buona presa su Git, dato che il mio progetto per il Sociale è ospitato su GitHub e da marzo contribuisco regolarmente a Open Food Facts e Mozilla Fenix. Sono un utente Linux da più di tre anni e da allora utilizzo comandi di terminale.

Gli strumenti di documentazione e i linguaggi che ho utilizzato sono Sphinx, Read the docs e Markdown. Mi è piaciuta questa idea e voglio lavorarci perché ho esperienza al riguardo e mi piacerebbe usare le mie conoscenze e competenze per contribuire al progetto DIPY. Ho esperienza nel campo dell'elaborazione digitale delle immagini, della visione artificiale, del machine learning. Mi aiuterà a comprendere meglio il neuroimaging e a creare documentazione. Ho una vasta esperienza nel campo medico. Ho sviluppato un sito web medico per medici, pazienti, laboratori, conducenti di ambulanza. Ho lavorato su un altro sistema usato da medici, pazienti, infermieri, assistenti di laboratorio e ricercatori. Questo mi aiuterà a creare una documentazione più facile da comprendere per il pubblico.

Ho esaminato la documentazione di DIPY e ho notato diversi difetti. La documentazione contiene molte scappatoie che ho intenzione di migliorare. Stato attuale della documentazione: La documentazione non dispone di una struttura e di un design specifici Può essere noiosa e dispendiosa in termini di tempo, specialmente per la navigazione dei nuovi utenti Per gli utenti è difficile ottenere informazioni dalla guida I contenuti della documentazione devono essere migliorati Come nuovo utente, ho avuto difficoltà ad accedere alla guida dell'utente e alla guida per gli sviluppatori. La documentazione deve essere rimodellata in modo che le informazioni richieste dall'utente siano facilmente accessibili La documentazione non è coerente

Ho intenzione di:

Definire una struttura e un modello specifici per la documentazione Rimodellare la documentazione in modo che gli utenti possano facilmente esplorare e trovare le informazioni richieste Creare una roadmap o un elenco di elementi di lavoro per coinvolgere la community in ulteriori attività di documentazione Definire modelli per la guida dell'utente e la guida per gli sviluppatori Definire modelli per la guida per i contributi Riscrivere, ristrutturare e aggiornare la guida dell'utente, la guida allo sviluppo e la guida per i contributi (che possono aiutare e motivare i nuovi utenti a contribuire al progetto) Creare una nuova documentazione testuale per migliorare l'interfaccia della documentazione non testuale

Guida dell'utente:

Per la guida dell'utente, mi soffermerei sull'uso di un linguaggio semplice per aiutare gli utenti a comprendere anche i sistemi più complessi. Per migliorare l'esperienza utente, vengono evitati gergo, acronimi e altre informazioni interne che un nuovo utente potrebbe non conoscere. Inoltre, mi soffermerò sull'utilizzo di contenuti visivi, tra cui immagini, screenshot annotati, elementi grafici e video, che mostrano rapidamente all'utente come funziona il sistema. Una buona documentazione richiede una gerarchia di intestazioni e sottotitoli che consenta all'utente di sapere cosa mostrerà in ogni sezione. Questa gerarchia deve seguire un flusso logico che aiuti l'utente a imparare a usare il sistema nel modo più utile. Uno degli obiettivi principali di questo progetto sarebbe la creazione di contenuti accessibili. Tutti i documenti e le guide devono rispettare uno stile coerente. È fondamentale utilizzare caratteri coerenti e colori complementari in più documenti. Mi assicurerò che gli utenti abbiano accesso a più risorse dell'organizzazione su come utilizzare al meglio il sistema.

Guida per gli sviluppatori:

La guida per gli sviluppatori include linee guida e materiali di riferimento completi per aiutare lo sviluppatore nella creazione di contributi al codice sorgente di DIPY. Prova a delineare le varie opzioni a tua disposizione, in modo da poter utilizzare l'approccio giusto, a seconda degli obiettivi che vuoi ottenere. La guida allo sviluppo richiede una ristrutturazione. Riscriverò i contenuti della guida per gli sviluppatori. Saranno inclusi e resi facilmente accessibili agli sviluppatori la creazione di dipendenze, la guida per il contributo, la guida di stile, le convenzioni di programmazione, la guida alla documentazione, l'installazione dell'ambiente di sviluppo, il debug, la guida ai test e gli elementi correlati. Quando i nuovi collaboratori ansiosi si precipitano verso il tuo progetto per dare il loro primo contributo open source, si affidano alle linee guida per il contributo come guida. Pertanto, le linee guida sarebbero facili da leggere, complete e amichevoli. Le guide per i contributi sono documenti utili che indicano in che modo le persone possono contribuire al progetto open source. Contribuire al progetto deve essere reso il più semplice e trasparente possibile per gli utenti, che si tratti di: Inviare una correzione Segnalazione di un bug Diventare un manutentore Parlare dello stato attuale del codice Proporre nuove funzionalità

TEMPLATE

Questo è uno dei modelli che possono essere utilizzati per la guida ai contributi. È possibile modificarlo e aggiungere o rimuovere sezioni in base ai requisiti del documento.

Contributo a DIPY

• Nota di benvenuto

Sommario

Codice di condotta

• I nostri standard
• Esempi di comportamenti che contribuiscono a creare un ambiente positivo
• Esempi di comportamenti non accettabili da parte dei partecipanti
• Le nostre responsabilità
• Responsabilità dei gestori del progetto
• Ambito

Ambito del codice di condotta

Cosa devo sapere per aiutarti?

Se hai bisogno di aiuto con un contributo al codice, il nostro progetto utilizza [inserisci l'elenco di linguaggi di programmazione, framework o strumenti utilizzati nel tuo progetto]. Se non ti senti ancora pronto per dare il tuo contributo con il codice, non c'è problema. Puoi anche consultare i problemi di documentazione [link to the docs label or tag on your issue tracker] o i problemi di progettazione disponibili [link to design label or tag on Issue Tracker se il tuo progetto tiene traccia dei problemi di progettazione]. Se vuoi contribuire al codice e saperne di più sulle tecnologie che utilizziamo, consulta l'elenco di seguito. Includi un elenco puntato di risorse (tutorial, video, libri) che i nuovi collaboratori possono utilizzare per scoprire ciò che gli utenti devono sapere per contribuire al progetto.

Configurazione dell'ambiente di sviluppo

In questa sezione, aggiungerò la procedura di installazione e le dipendenze che devono essere installate. Installa $project eseguendo: installa progetto

• Codice sorgente: github.com/$project/$project
• Monitoraggio problemi: github.com/$project/$project/issues

Come dare il proprio contributo

Come segnalare un problema

• Prima di inviare una segnalazione di bug
• Come faccio a inviare una segnalazione di bug (buona)?

Come inviare le modifiche

• Protocolli di richiesta di pull
• Risposta dal team
• Velocità di risposta

Come richiedere un miglioramento

• Prima di inviare un suggerimento relativo al miglioramento
• Come faccio a inviare un suggerimento (buono) per il miglioramento?

Il tuo primo contributo al codice

• Problemi principianti
• Richiesta di assistenza relativa ai problemi #### Richiesta di pull
• Procedura di creazione della richiesta di pull
• Verifica che tutti i controlli dello stato siano superati.

Che cosa succede se i controlli dello stato non vanno a buon fine?

• Test di scrittura
• Copertura del test

Guide di stile

• Messaggi di commit Git
• Stile standard

Assistenza

In caso di problemi, non esitare a contattarci. Se hai bisogno di assistenza, puoi porre domande nella nostra mailing list all'indirizzo: [e-mail], nella chat di IRC oppure [elenco di eventuali altre piattaforme di comunicazione utilizzate dal tuo progetto].

Licenza

Questa sezione descrive la licenza del progetto.

Impegno in termini di tempo e comunicazione:

Darò più di 45 ore a settimana, ma in caso di disguido, compenserò queste ore nei fine settimana. Durante il periodo di legame tra comunità, parlerò dei mezzi di comunicazione e finalizzerò gli incontri settimanali, i mezzi e il tempo per gli incontri con il mio mentore. Terrò aggiornato sul mio lavoro il mio mentore e condividerò i dettagli del lavoro via email. Preferisco TeamViewer per le comunicazioni, poiché è facile da usare e offre molte funzionalità, come le schermate di condivisione e così via.