Progetto DIPY

Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.

Riepilogo del progetto

Organizzazione open source:

DIPY

Redattore tecnico:

Areesha Tariq

Nome del progetto:

Ristrutturazione di alto livello e attenzione all'utente finale

Durata del progetto:

Durata standard (3 mesi)

Project description

Sono ingegnere informatico e ho esperienza in scrittura tecnica. Ho oltre 4 anni di esperienza nella creazione di documentazione software, guide per l'utente, manuali e descrizioni dei progetti di alta qualità. Vivo a Islamabad, in Pakistan (fuso orario: UTC + 5). Attualmente lavoro come stagista in Outreachy, che continuerà fino al 18 agosto. Ho partecipato alla Stagione di Google Documenti come Technical Writer nell'organizzazione OpenELIS Global. La documentazione originale era in francese, limitata e obsoleta, quindi ho creato una documentazione completa e aggiornata per gli utenti finali in inglese. Sono stato selezionato per Outreachy nell'organizzazione Perl & Raku per il round di maggio-agosto 2020 come sviluppatore backend del server Open Food Facts. Oltre allo sviluppo back-end, una delle principali attività di questo tirocinio è creare la documentazione per i moduli e le funzioni in formato POD. Ho iniziato a interessarmi al mondo open source l'anno scorso quando ho contribuito ad alcuni progetti open source e in seguito ho partecipato alla stagione dei documenti di Google. Quest'anno sono stata selezionata per Outreachy, che supporta la diversità nel software libero e open source. Ho una buona conoscenza di Git perché il mio progetto Outreachy è ospitato su GitHub e da marzo fornisco contributi regolari a Open Food Facts e Mozilla Fenix. Sono un utente Linux da più di 3 anni e da allora utilizzo i comandi del terminale.

Gli strumenti e i linguaggi di documentazione che ho utilizzato sono Sphinx, Read the docs e Markdown. Mi è piaciuta questa idea e voglio lavorarci perché ho un'esperienza pertinente e mi piacerebbe usare le mie conoscenze e competenze per contribuire a fai da te. Ho esperienza nel campo dell'elaborazione di immagini digitali, della visione artificiale e del machine learning. Mi aiuterà a comprendere meglio la neuroimmagine e a creare la documentazione. Ho una vasta esperienza nel campo della medicina. Ho sviluppato un sito web medico per medici, pazienti, laboratori, autisti di ambulanze. Ho lavorato a un altro sistema utilizzato da medici, pazienti, infermieri, assistenti di laboratorio e ricercatori. In questo modo, potrò creare una documentazione più facile da comprendere per il pubblico.

Ho esaminato la documentazione di DIPY e ho notato diversi difetti. La documentazione contiene diverse falle che intendo migliorare. Stato attuale della documentazione: La documentazione manca di una struttura e un design specifici La navigazione può essere tediosa e richiedere molto tempo, soprattutto per i nuovi utenti Gli utenti possono avere difficoltà a ottenere informazioni dalla guida I contenuti della documentazione devono essere migliorati In qualità di nuovo utente, ho avuto difficoltà ad accedere alla guida dell'utente e alla guida per gli sviluppatori. La documentazione deve essere riorganizzata in modo che le informazioni richieste dall'utente siano facilmente accessibili La documentazione non è coerente

Ho intenzione di procedere nel seguente modo:

Definire una struttura e un modello specifici per la documentazione Rimodellare la documentazione in modo che gli utenti possano facilmente navigare e trovare le informazioni richieste Creare una roadmap o un elenco di elementi di lavoro per coinvolgere la community in ulteriori lavori di documentazione Definire modelli per la guida dell'utente e la guida per gli sviluppatori Definire modelli per contribuire alla guida Riscrivere, ristrutturare e aggiornare la guida dell'utente, la guida allo sviluppo e la guida che contribuisce (che può aiutare e motivare i nuovi utenti a contribuire alla coerenza della documentazione) Aggiungere la documentazione non testuale

Guida dell'utente:

Per la guida dell'utente, mi concentrerei sull'utilizzo di un linguaggio semplice e chiaro per aiutare gli utenti a comprendere anche i sistemi più complessi. Per una migliore esperienza utente, vengono evitati gergo, acronimi e altre informazioni privilegiate che un nuovo utente potrebbe non conoscere. Mi concentrerò anche sull'utilizzo di contenuti visivi, tra cui immagini, screenshot annotati, grafici e video, che mostrano rapidamente all'utente il funzionamento del sistema. Una buona documentazione richiede una gerarchia di intestazioni e sottotitoli che consenta all'utente di sapere cosa gli verrà mostrato in ogni sezione. Questa gerarchia deve seguire un flusso logico che aiuti l'utente a imparare a utilizzare il sistema nel modo più utile. Uno dei principali obiettivi di questo progetto è la creazione di contenuti accessibili. Tutti i documenti e le guide rispetteranno uno stile coerente. L'utilizzo di caratteri e colori complementari coerenti in più documenti è un must. 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 indicazioni esaustive e materiali di riferimento per aiutare lo sviluppatore a creare contributi per il codice sorgente di DIPY. Tenta di illustrare le varie opzioni a tua disposizione, in modo che tu possa utilizzare l'approccio giusto, a seconda di ciò che vuoi ottenere. La guida allo sviluppo deve essere riorganizzata e ristrutturata. Riscriverò i contenuti della guida per gli sviluppatori. Le dipendenze di compilazione, la guida per i collaboratori, la guida di stile, le convenzioni di codifica, la guida alla documentazione, l'installazione dell'ambiente di sviluppo, il debug, la guida ai test e gli elementi correlati verranno inclusi e resi facilmente accessibili agli sviluppatori. Quando i nuovi collaboratori si precipitano nel tuo progetto per apportare il loro primo contributo open source, si affidano alle linee guida per i collaboratori per avere una guida. In questo modo, le linee guida saranno facili da leggere, complete e amichevoli. Le guide per i collaboratori sono documenti utili che spiegano come le persone possono contribuire al progetto open source. Il contributo al progetto deve essere reso il più semplice e trasparente possibile per gli utenti, che si tratti di: Inviare una correzione Segnalare un bug Diventare un manutentore Discutere dello stato attuale del codice Proporre nuove funzionalità

TEMPLATE

Questo è uno dei modelli che possono essere utilizzati per la guida ai contributi. Può essere modificato e le sezioni possono essere aggiunte o rimosse in base ai requisiti del documento.

Contributo al DIPY

• Nota di benvenuto

Sommario

Codice di condotta

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

Ambito del Codice di condotta

Che cosa devo sapere per aiutarti?

Se hai bisogno di aiuto con un contributo al codice, il nostro progetto utilizza [inserisci l'elenco dei linguaggi di programmazione, dei framework o degli strumenti utilizzati dal tuo progetto]. Se non ritieni di essere ancora pronto a contribuire con il codice, non preoccuparti. Puoi anche controllare i problemi relativi alla documentazione [link all'etichetta o al tag della documentazione nel tracker dei problemi] o i problemi di progettazione che abbiamo [link all'etichetta o al tag di progettazione nel tracker dei problemi se il tuo progetto monitora i problemi di progettazione]. Se vuoi contribuire con il codice e vuoi 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 cosa devono sapere per contribuire al progetto.

Configurazione dell'ambiente di sviluppo

In questa sezione aggiungerò la procedura di installazione e le dipendenze da installare. Installa $project eseguendo: install project

• Codice sorgente: github.com/$project/$project
• Issue Tracker: 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 (corretta)?

Come inviare le modifiche

• Protocolli delle richieste di pull
• Risposta del team
• Velocità di risposta

Come richiedere un miglioramento

• Prima di inviare un suggerimento di miglioramento
• Come faccio a inviare un buon suggerimento di miglioramento?

Il tuo primo contributo di codice

• Problemi per principianti
• Problemi relativi alla richiesta di assistenza #### Richiesta di pull
• Processo di creazione della richiesta di pull
• Verifica che tutti i controlli dello stato siano stati superati.

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

• Test di scrittura
• Copertura test

Guide di stile

• Messaggi di commit Git
• Stile standard

Assistenza

In caso di problemi, non esitare a contattarci. Se hai bisogno di aiuto, puoi porre domande alla nostra mailing list all'indirizzo [e-mail], nella chat IRC o [elenca le altre piattaforme di comunicazione utilizzate dal tuo progetto].

Licenza

Questa sezione illustra la licenza del progetto.

Impegno in termini di tempo e comunicazione:

Offro più di 45 ore a settimana, ma in caso di imprevisti, compenserò queste ore nei fine settimana. Durante il periodo di legame della community, parlerò dei mezzi di comunicazione e definirò gli incontri settimanali, i mezzi e l'orario di questi incontri con il mio mentore. Terrò aggiornato il mio mentore sul mio lavoro e condividerò i dettagli del mio lavoro via email con il mio mentore. Preferisco TeamViewer per la comunicazione, perché è facile da usare e offre molte funzionalità, come la condivisione dello schermo e così via.