progetto globale moja

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

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 all'onboarding per FLINT 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 manutentori.

Problemi relativi al progetto

Di seguito è riportato un elenco dei problemi più cruciali relativi alla documentazione attuale: - Parti disorganizzate delle istruzioni della guida alla configurazione locale, che rendono difficile l'avvio di un nuovo collaboratore. - Più repository di FLINT non dispongono di documentazione relativa al 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 può essere migliorata. - 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 manutentori. A questo scopo, è possibile eseguire il refactoring della documentazione attuale per renderla più 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 è esaminare la guida attuale e riformularla in modo da renderla concisa e facilmente comprensibile da parte dei nuovi collaboratori. Inoltre, la documentazione deve essere modificata per renderla più adatta ai principianti aggiungendo badge, emoji e informazioni sui problemi etichettati con tag "Solo per nuovi utenti" o "Primo problema" valido. - Creare un repository di documentazione autonomo centrale: l'obiettivo di questa fase è collegare tutta la documentazione disponibile in ordine sequenziale logico in un repository autonomo. A questo scopo, devi ordinare le linee guida per i contributi, le istruzioni per la configurazione del progetto e le guide passo passo. - Aggiunta del flusso di lavoro degli sviluppatori e del sito web della community per i nuovi sviluppatori: l'obiettivo di questa fase è aggiungere il flusso di lavoro per sviluppatori contenente le linee guida per i contributi Git e l'architettura tecnica 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 dei nuovi utenti che possono essere rivendicati dai nuovi collaboratori e un elenco di tutti i collaboratori. Fase 1: esamina la documentazione esistente e il refactoring:

Modifica la documentazione attuale dei seguenti repository: - FLINT: la documentazione attuale non è molto dettagliata e non fornisce un ordine sequenziale delle librerie prerequisito richieste. Le guide di istruzioni 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 dell'impostazione di questo repository, che è quello 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 inoltre porre l'accento sul modo sequenziale di impostazione dei file Docker e anche su informazioni sufficienti su come creare dal makefile. - FLINT.example: la documentazione attuale non fornisce lo scopo dell'impostazione di questo repository, che fornisce 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, in modo che gli utenti possano navigare qui per vedere l'esempio in azione.

Le seguenti informazioni devono essere aggiunte alla documentazione attuale: - Utilizzo di Git e GitHub: includerà istruzioni dettagliate su come effettuare il fork, clonare e configurare l'upstream remoto per il repository. Fornirà inoltre informazioni su come eseguire il rebase rispetto all'ultimo master e gestire i conflitti di unione. - Badge ed emoji: la documentazione attuale è priva di badge ed emoji, che possono aiutare i nuovi collaboratori a sentirsi accolti e a trovare i problemi meno scoraggianti. - Informazioni sui problemi relativi ai primi timer/per i principianti: ciò ti 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 rapido 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 i programmatori per suggerire funzionalità aggiuntive per il repository Import-me.

Fase 2: crea un repository centrale autonomo della documentazione.

Strumento da utilizzare per la piattaforma di hosting:

Lo strumento proposto per questa piattaforma di hosting è Read The Docs per i seguenti motivi:- - Ha ottenuto 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 grande community che lo utilizza - La documentazione è formattata utilizzando reStructuredText e l'output è compilato da Sphinx.

Organizza 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à presentata un'introduzione a Moja Global e FLINT. - Contributi: questa sezione è composta dalle 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". - Flusso di lavoro dello sviluppatore: questa sezione consiste in ulteriori fasi di test e di test sugli strumenti integrati - 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 sul flusso di lavoro per sviluppatori:

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

• Stack tecnico/architettura utilizzato e i vari moduli del codice: documentazione per far conoscere ai nuovi collaboratori lo stack tecnico implementato, le varie librerie e i moduli del codebase.
• 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 di qualità eseguiti sul loro codice. Fornisce inoltre linee guida su chi rivolgersi nel caso in cui i test non vadano a buon fine.
• Bot usati per semplificare 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 e invio manuale 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 delle richieste 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 manutentori 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 consiste 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, seguite dalla creazione di un problema per la prima volta per qualcun altro e dall'aiutare gli altri utenti fornendo un feedback ed esaminando le richieste di pull.
• Elenco di problemi che interessano solo la prima volta il timer: l'elenco di problemi pensato specificamente per i nuovi utenti o per i 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 di collaboratori che di recente hanno contribuito ai repository Moja Global.
• Link per partecipare ai forum di chat: informazioni e link per partecipare alla community Slack al fine di risolvere le domande e sostenere ulteriori discussioni sui progetti.