progetto globale moja

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.

Riepilogo del progetto

Organizzazione open source:

moja globale

Technical writer:

Tlazypanda

Nome progetto:

Documentazione della guida tecnica alle operazioni preliminari per FLINT

Durata del progetto:

Durata standard (3 mesi)

Project description

Documentazione della guida tecnica di onboarding per FLINT per guidare i nuovi collaboratori attraverso un onboarding tecnico in modo che i nuovi collaboratori possano iniziare facilmente con il supporto minimo da parte dei gestori.

Problemi relativi al progetto

Di seguito è riportato un elenco dei problemi più cruciali relativi alla documentazione attuale: - Articoli disorganizzati delle istruzioni della guida alla configurazione locale che rendono difficile l'avvio di un nuovo collaboratore. - Più repository di FLINT non dispongono di documentazione sul loro scopo e non sono collegati tra loro, il che rende difficile per il nuovo arrivato identificare il repository da installare. - L'installazione di Windows è ben documentata, ma la documentazione di installazione basata su Linux ha margini di miglioramento. - Il flusso di lavoro Git non fa attualmente parte della documentazione

Soluzione proposta

Questa proposta presenta una soluzione per guidare i nuovi collaboratori attraverso un onboarding tecnico in modo che i nuovi collaboratori possano facilmente iniziare con un'assistenza minima da parte dei gestori. Ciò può essere ottenuto con il refactoring della documentazione attuale per renderla adatta ai principianti e mantenere anche un repository autonomo centrale per tutta la documentazione disponibile. Il progetto è suddiviso in tre fasi:- Revisione della documentazione esistente e refactoring: l'obiettivo di questa fase è rivedere la guida attuale e rielaborarla in modo da renderla concisa e facilmente comprensibile dai nuovi collaboratori. Inoltre, la documentazione deve essere modificata per renderla più facile da usare per i principianti, aggiungendo badge, emoji e informazioni sui problemi etichettati con tag che interessano solo i nuovi utenti o il primo problema. - Creare un repository di documentazione centralizzato centrale: l'obiettivo di questa fase è collegare tutta la documentazione disponibile in un ordine logico sequenziale in un repository autonomo. Ciò comporta l'ordinazione delle linee guida per i contributi, delle istruzioni per la configurazione del progetto e delle guide passo passo. - Aggiunta del flusso di lavoro dello sviluppatore e del sito web della community per i nuovi sviluppatori: l'obiettivo di questa fase è aggiungere il flusso di lavoro dello sviluppatore che contiene le linee guida per i contributi Git e l'architettura tecnologica del progetto, oltre alle linee guida per i test e il QA. Il sito web della community proposto sarà un'applicazione a pagina singola che mostra il flusso di lavoro, i problemi per i nuovi utenti che possono essere rivendicati dai nuovi collaboratori e un elenco di tutti i collaboratori. Fase 1: revisione della documentazione esistente e del refactoring

Modifica la documentazione attuale dei seguenti repository: - FLINT: la documentazione attuale non è molto dettagliata e non fornisce un ordine sequenziale delle librerie prerequisiti necessarie. Le guide passo passo sono suddivise in diversi file PDF, ma possono essere unite in un unico posto in modo più conciso. Inoltre, le guide all'installazione sono pensate per le finestre, ma per l'installazione Linux il reindirizzamento al repository FLINT.docker potrebbe essere utile. - FLINT.docker: la documentazione attuale non fornisce lo scopo alla base dell'impostazione di questo repository, ovvero di fornire l'installazione Linux di FLINT tramite docker. Il supporto tramite docker è limitato solo a Ubuntu 18.04 (Bionic Beaver) ma può essere esteso ad altre distribuzioni basate su Linux. La documentazione attuale deve porre l'attenzione sul modo sequenziale di impostazione dei file Docker e sufficienti informazioni su come creare file dal makefile. - FLINT.example: la documentazione attuale non fornisce lo scopo alla base dell'impostazione di questo repository, che è fornire un esempio di come utilizzare FLINT. Le diverse esecuzioni di esempio possono essere meglio separate con istruzioni specifiche per l'esecuzione. Dobbiamo anche collegare questo repository al nostro repository FLINT principale, per fornire agli utenti un modo per navigare qui per vedere l'esempio in azione.

È necessario aggiungere le seguenti informazioni alla documentazione attuale: - Utilizzo di Git e GitHub: include istruzioni dettagliate su come eseguire il fork, clonare e configurare l'upstream remoto per il repository. Fornisce inoltre informazioni su come basare la base rispetto all'ultimo master e gestire i conflitti di unione. - Badge ed emoji: l'attuale documentazione non contiene badge ed emoji, che possono aiutare i nuovi collaboratori a sentirsi accolti e a individuare i problemi meno scoraggianti. - Informazioni sui primi timer/problemi adatti ai principianti: questo aiuterà a reindirizzare i nuovi collaboratori a problemi adatti ai principianti e al sito web della community. - Informazioni sul repository Import-me: il repository Import-me funge da modello di base per l'avvio di qualsiasi repository Moja Global. La documentazione attuale non ne menziona l'importanza. Deve essere aggiornato per menzionare il repository Import-me e devono essere aggiunti anche i passaggi per sceglierlo come modello per la creazione di un nuovo repository. Dovrebbe anche esserci un processo consolidato per consentire ai programmatori di suggerire funzionalità aggiuntive per il repository Import-me.

Fase 2: crea un repository di documentazione centralizzato centrale

Strumento da utilizzare per la piattaforma di hosting:

Gli strumenti proposti per questa piattaforma di hosting è Read The Docs per i seguenti motivi:- Ha un ranking elevato tra le diverse piattaforme di hosting. - Aggiornamento automatico al push del commit - Supporto facile da configurare e per la risoluzione dei problemi disponibile facilmente grazie alla vasta community che lo utilizza - La documentazione è formattata utilizzando reStructuredText e l'output è stato compilato da Sphinx.

Organizzare tutti i contenuti in modo logico e sequenziale:

L'ordine dei contenuti proposto è il seguente:- - Introduzione alla documentazione per gli sviluppatori: in questa sezione verrà fornita un'introduzione a Moja Global e FLINT. - Contribuire: questa sezione comprende le sottosezioni "Modi per contribuire" (in termini di codice/segnalazione di bug/traduzione/documentazione/organizzazione di eventi ecc.) e "Codice di condotta". - Configurazione dello sviluppo: questa sezione è composta da sottosezioni "Flusso di lavoro Git e GitHub", "Installazione di Windows", "Installazione di Linux", "Installazione di Linux". - Flusso di lavoro degli sviluppatori: questa sezione tratterà la fase successiva di test sugli strumenti e su come eseguire i test manuali degli strumenti. - Unisciti a noi: questa sezione fornirà i vari social forum, come i canali Slack per connettersi e collaborare con Moja Global.

Fase 3: aggiungi il flusso di lavoro degli sviluppatori e il sito web della community per i nuovi collaboratori

Documentazione del flusso di lavoro degli sviluppatori:

La documentazione relativa al flusso di lavoro degli sviluppatori è costituita dalle seguenti sottosezioni:

• Stack tecnico/architettura utilizzati e vari moduli nel codice: documentazione per familiarizzare i nuovi collaboratori con lo stack tecnico implementato, le varie librerie e i vari moduli del codebase.
• Gli strumenti integrati di test e copertura: presentazione di nuovi collaboratori agli strumenti della pipeline CI/CD utilizzati per i test, ai bot di copertura e ai controlli automatici della qualità eseguiti sul loro codice. Inoltre, fornisce loro delle linee guida su chi affrontare se i test hanno esito negativo.
• Bot usati per facilitare il flusso di lavoro, ad esempio Zulipbot: progettazione di modelli di contenuti per la visualizzazione dei bot e documentazione da rendere disponibile per consentire agli utenti di comprendere i bot e persino migliorarne la configurazione contribuendo.
• Test manuale e invio di una richiesta pull: documentazione da fornire su come testare manualmente le richieste Pull in base a determinati standard e caricare i risultati in termini di screenshot/gif all'invio di richieste di pull.
• Linee guida per la revisione delle richieste di pull che i collaboratori devono seguire: linee guida sul tagging di determinati team per la revisione e sull'aggiunta di etichette come "da rivedere" alla richiesta di pull per consentire ai gestori di rispondere.

Sito web della community:

Il sito web della community avrà le seguenti funzionalità:

• Informazioni sul nostro flusso di lavoro: il flusso di lavoro consisterà in una serie di azioni con cui un nuovo collaboratore può iniziare, ad esempio la rivendicazione di un problema che si verifica per la prima volta, seguita dalla creazione di un problema per la prima volta per qualcun altro e dall'aiuto agli altri fornendo feedback ed esaminando le loro richieste di pull.
• Elenco di problemi che interessano solo il primo timer: l'elenco di problemi destinati specificamente a utenti neofiti o nuovi collaboratori.
• Elenco dei problemi inattivi: l'elenco dei problemi che non sono stati risolti per un lungo periodo di tempo e che quindi possono essere scelti dai collaboratori.
• Elenco dei collaboratori: l'elenco dei collaboratori che hanno contribuito finora ai repository di Moja Global.
• Collaboratori recenti: l'elenco dei collaboratori che di recente hanno dato il loro contributo ai repository Moja Global.
• Link per partecipare ai forum di chat: informazioni e link per partecipare alla community Slack al fine di risolvere le query e partecipare a ulteriori discussioni sui progetti.