Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- moja global
- Redattore tecnico:
- Tlazypanda
- Nome progetto:
- Documentazione della guida all'onboarding tecnico per FLINT
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Documentazione della Guida all'onboarding tecnico per FLINT per guidare i nuovi collaboratori attraverso un onboarding tecnico in modo che possano iniziare facilmente con un supporto minimo da parte dei manutentori.
Problemi del progetto
Di seguito è riportato un elenco dei problemi più importanti relativi alla documentazione attuale: - Informazioni disorganizzate nelle istruzioni della guida alla configurazione locale che rendono difficile per un nuovo collaboratore iniziare. - Diversi repository di FLINT non dispongono di documentazione relativa allo scopo e non sono collegati tra loro, il che rende difficile per i neofiti identificare il repository da installare. - L'installazione su Windows è ben documentata, ma la documentazione relativa all'installazione su Linux ha margini di miglioramento. - Il flusso di lavoro di 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 possano iniziare facilmente con un supporto minimo da parte dei manutentori. Questo può essere ottenuto ristrutturando la documentazione attuale per renderla adatta ai principianti e anche per mantenere un repository autonomo centrale per tutta la documentazione disponibile. Il progetto è suddiviso in tre fasi:- - Revisione della documentazione esistente e refactoring: lo scopo di questa fase è rivedere la guida attuale e rifarne il refactoring in modo che sia concisa e facilmente comprensibile dai nuovi collaboratori. Inoltre, la documentazione deve essere modificata per renderla più adatta ai principianti aggiungendo badge, emoji e informazioni su problemi contrassegnati con tag Solo per i neofiti o Primo problema. - Crea un repository di documentazione autonomo centrale: lo scopo di questa fase è collegare tutta la documentazione disponibile in un ordine sequenziale logico in un repository autonomo. Ciò comporta l'ordinamento delle linee guida per i contributi, le istruzioni di configurazione del progetto e le 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 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 per i neofiti che possono essere rivendicati dai nuovi collaboratori e un elenco di tutti i collaboratori. Fase 1: esamina la documentazione esistente e il refactoring:
Modificare la documentazione attuale dei seguenti repository: - FLINT: la documentazione attuale non è molto dettagliata e non fornisce un ordine sequenziale delle librerie di prerequisiti richieste. Le guide di istruzioni passo passo sono suddivise in diversi PDF, ma possono essere unificate in un unico posto in modo più conciso. Inoltre, le guide all'installazione sono rivolte a Windows, ma per l'installazione su Linux potrebbe essere utile il reindirizzamento al repository FLINT.docker. - FLINT.docker: la documentazione attuale non fornisce lo scopo alla base dell'impostazione di questo repository, ovvero fornire l'installazione di FLINT su Linux 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 anche mettere in evidenza la modalità sequenziale di configurazione dei file Docker e fornire informazioni sufficienti su come eseguire il build dal file makefile. - FLINT.example: la documentazione attuale non fornisce lo scopo alla base dell'impostazione di questo repository, ovvero fornire un esempio di come utilizzare FLINT. Le diverse esecuzioni di esempio possono essere separate meglio con istruzioni specifiche da eseguire. Dobbiamo anche collegare questo repository al nostro repository FLINT principale, fornendo agli utenti un modo per navigare qui per controllare l'esempio in azione.
È necessario aggiungere le seguenti informazioni alla documentazione corrente: - Utilizzo di Git e GitHub: saranno incluse istruzioni dettagliate su come creare un fork, clonare e impostare l'upstream remoto per il repository. Fornisce inoltre informazioni su come ribase rispetto all'ultimo master e gestire i conflitti di unione. - Badge ed emoji: la documentazione attuale non contiene badge ed emoji che possono aiutare i nuovi collaboratori a sentirsi accolti e a trovare i problemi meno scoraggianti. - Informazioni sui problemi per principianti/principianti: ti aiuteranno 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 riferimento per avviare qualsiasi repository Moja Global. La documentazione attuale non menziona l'importanza di questo aspetto. Deve essere aggiornato per menzionare il repository Import-me e devono essere aggiunti anche i passaggi per sceglierlo come modello durante la creazione di un nuovo repository. Deve anche esistere un processo consolidato per i programmatori che suggeriscano funzionalità aggiuntive per il repository Import-me.
Fase 2: crea un repository di documentazione autonomo centrale :
Strumento da utilizzare per la piattaforma di hosting:
Gli strumenti proposti per questa piattaforma di hosting sono Read The Docs per i seguenti motivi:- - Ha un ranking elevato tra le diverse piattaforme di hosting. - Aggiornamento automatico al commit push - Facile da configurare e assistenza per la risoluzione dei problemi disponibile facilmente grazie alla grande community che lo utilizza - La documentazione è formattata utilizzando reStructuredText e l'output viene compilato da Sphinx.
Organizza tutti i contenuti in modo sequenziale e logico:
L'ordine proposto dei contenuti è il seguente:- - Introduzione alla documentazione per gli sviluppatori: questa sezione fornirà un'introduzione a Moja Global e FLINT. - Contributi: questa sezione sarà composta dalle sottosezioni "Modalità di contributo" (in termini di codice/segnalazione di bug/traduzione/documentazione/organizzazione di eventi e così via) e "Codice di condotta". - Configurazione dello sviluppo: questa sezione sarà composta dalle sottosezioni "Flusso di lavoro di Git e GitHub", "Installazione di Windows", "Installazione di Linux". - Flusso di lavoro dello sviluppatore: questa sezione sarà composta da una discussione sugli strumenti integrati per i test e su come eseguire test manuali sulla pull request e altro ancora, come documentato nella fase successiva. - Unisciti a noi: questa sezione fornisce i vari forum di social come i canali Slack per entrare in contatto e collaborare con Moja Global.
Fase 3: aggiungi il flusso di lavoro per gli sviluppatori e il sito web della community per i nuovi collaboratori:
Documentazione sul flusso di lavoro per gli sviluppatori:
La documentazione del flusso di lavoro per gli sviluppatori sarà composta dalle seguenti sezioni:
- Tech Stack/Architettura utilizzata e i vari moduli nel codice: documentazione per familiarizzare i nuovi collaboratori con la tecnologia implementata, le varie librerie e i moduli della base di codice.
- Gli strumenti di test e copertura integrati: introduzione di nuovi collaboratori agli strumenti della pipeline CI/CD utilizzati per i test, i bot di copertura e i controlli di qualità automatici eseguiti sul loro codice. Fornire inoltre linee guida su chi contattare in caso di fallimento dei test.
- Bot utilizzati per semplificare il flusso di lavoro, ad esempio Zulipbot: progettazione di modelli di contenuti da visualizzare per i bot e documentazione disponibile per consentire agli utenti di comprendere i bot e persino di migliorarne la configurazione contribuendo.
- Test manuale e invio di una richiesta di pull: documentazione da fornire su come testare manualmente le richieste di pull in base a determinati standard e caricare i risultati sotto forma di screenshot/GIF al momento dell'invio delle richieste di pull.
- Linee guida per la revisione delle richieste pull che devono essere seguite dai collaboratori: linee guida su come taggare determinati team per la revisione e aggiungere etichette, come "richiede revisione", 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à nella serie di azioni che un nuovo collaboratore può iniziare, ad esempio richiedere un problema per i neofiti, creare un problema per i neofiti per qualcun altro e aiutare gli altri fornendo feedback e esaminando le loro richieste pull.
- Elenco di problemi solo per i primi autori: l'elenco di problemi specifici per i primi autori o i nuovi collaboratori.
- Elenco di problemi inattivi: l'elenco dei problemi su cui non si lavora da molto tempo e che possono essere scelti dai collaboratori.
- Elenco dei collaboratori: l'elenco dei collaboratori che hanno finora contribuito ai repository di Moja Global.
- Collaboratori recenti: l'elenco dei collaboratori che hanno contribuito di recente ai repository di Moja Global.
- Link per partecipare ai forum di chat: informazioni e link per partecipare alla community di Slack per risolvere le query e continuare a discutere dei progetti.