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:
- Electron
- Redattore tecnico:
- Mister Gold
- Nome del progetto:
- Flusso del tutorial sull'elettrone
- Durata del progetto:
- Durata standard (3 mesi)
Project description
RIEPILOGO DEL PROGETTO
Electron è uno degli strumenti più utilizzati per creare app desktop multipiattaforma con JavaScript, HTML e CSS. Una raccolta di app create su Electron ha quasi 900 voci e questo elenco è in continua crescita. Alcuni degli strumenti per sviluppatori più utilizzati come Visual Studio Code, Atom, Postman, Slack e GitKraken sono basati su Electron.
La popolarità di Electron sta nella sua semplice curva di apprendimento e nella bassa soglia di accesso: chiunque conosca lo stack JavaScript, HTML e CSS può creare la propria applicazione. I tassi di crescita complessivi elevati impongono la necessità di creare tutorial e guide introduttive facili da comprendere e utilizzare.
L'obiettivo del progetto è offrire sicurezza ai creator di app che non hanno dimestichezza con il framework Electron e fornire loro un'esperienza coerente e semplificata per lo sviluppo delle proprie applicazioni Electron da zero.
Problemi relativi ai progetti
Di seguito è riportato un elenco dei problemi più importanti relativi alla documentazione dei tutorial su Electron: 1. Punto di partenza non chiaro e informazioni introduttive non intuitive sui passaggi di sviluppo dell'applicazione. 2 Informazioni sparse e ridondanti relative alla procedura di sviluppo delle applicazioni. 3 Istruzioni disorganizzate della guida "Inizia" senza un'unica fonte attendibile
PROPOSTA DI PROGETTO
In base all'obiettivo del progetto e ai problemi sopra descritti, di seguito è riportato un elenco dei miglioramenti proposti: 1. Aggiorna le guide esistenti. Per rendere i primi passaggi fluidi e coerenti, i seguenti documenti dovrebbero essere aggiornati con un passaggio graduale da semplice a più complesso: - Ambiente di sviluppo - Scrittura della tua prima app Electron - Aggiunta di funzionalità all'app (crea una pagina di riepilogo) - Packaging e distribuzione delle app 2. Ristruttura la directory della documentazione. Per mostrare ai nuovi sviluppatori gli elementi essenziali per iniziare e quelli che possono essere considerati come passaggi successivi, la pagina della documentazione deve presentare una suddivisione sia visiva che contestuale dei passaggi, in modo da rendere attiva il più velocemente possibile la prima applicazione. La ristrutturazione include anche indicazioni sui possibili passaggi successivi. 3. Organizza e unifica la documentazione di sviluppo delle applicazioni. Tutte le funzionalità devono avere un insieme unificato di istruzioni su come installarla/attivarla, come iniziare rapidamente, come utilizzare un'app dopo il primo lancio e come distribuirla. 4. Includi il repository electron-api-demos nella documentazione. Il repository electron-api-demos contiene una serie di esempi che mostrano come aggiungere funzionalità all'applicazione Electron. Queste informazioni devono essere incluse nella guida Aggiunta di funzionalità all'app per essere coerenti con una strategia per i contenuti basata su una singola fonte attendibile. 5. Integrare gli esempi di Electron Fiddle nella documentazione. Questo passaggio consentirà ai nuovi sviluppatori di capire più facilmente come funziona una determinata porzione di codice, senza dover ripetere i passaggi manualmente. L'integrazione include la scrittura di esempi di codice per i tutorial aggiornati e l'aggiunta del pulsante "Avvia in Fiddle" ai blocchi di codice.
Cronaca
Periodo di revisione delle candidature: familiarizza con la community e le persone con cui collaborerai. Scopri le guide e le best practice per i contributi della community. Pubblica i primi contributi. Community Bonding: esplora la community. Controlla lo stato attuale della documentazione di Electron. Identifica i punti deboli. Settimana 1 - Allineati con i mentori sui traguardi e sui risultati finali del progetto Settimana 2 - Riesamina l'ambiente di sviluppo e la scrittura delle pagine della tua prima app Electron Settimana 3 - Rivedere l'architettura delle applicazioni, aggiungere funzionalità all'app, Packaging delle app e pagine di distribuzione. Crea una pagina di riepilogo con un elenco di funzionalità che possono essere aggiunte all'app Settimana 4 - Ristruttura la directory della documentazione Settimana 5 - Prepara un modello per l'integrazione di elettronican-api-demos nella documentazione principale Settimane 6 - 7 - Migrazione del repository elettronica-api-demos Settimana 8 - Prepara un modello per l'integrazione della documentazione principale di Electron Fiddle. Scrivi il primo campione. Settimane 9-10: integrazione di Electron Fiddle nella documentazione principale Settimana 11: finalizzazione della struttura e delle pagine della documentazione principale dopo la migrazione del repository electron-api-demos e dei sample di Electron Fiddle Settimana 12: valutazione dei risultati
RIPARTIZIONE DETTAGLIATA DEGLI TRASFERIMENTI
PERIODO DI REVISIONE DELLE DOMANDE La prima parte del periodo sarà dedicata al controllo dei canali della community e del codice sorgente e al contatto delle persone dedicate al progetto.
La seconda parte del periodo sarà dedicata al controllo della cultura dei contributi in generale, con l'esame di guide e best practice sui contributi. Sarà il momento dei primi contributi per capire come funziona il flusso.
RELAZIONI DI COMUNITÀ
Questa volta sarà dedicata a un esame più approfondito della cartella della documentazione e della relativa roadmap. Sulla base di queste informazioni, sarà possibile identificare i punti deboli (ad es. parti incomplete o mancanti) che possono essere migliorati. Crea pull request (se possibile) per colmare le lacune.
SETTIMANA 1 - SETTIMANA 2
La prima settimana sarà dedicata alla comunicazione con i mentor per allinearsi ai traguardi previsti e alla loro consegna puntuale.
La seconda settimana sarà dedicata alla revisione delle pagine sull'ambiente di sviluppo e sulla scrittura della tua prima app Electron. Per la pagina Ambiente sviluppatore, includerà la riscrittura della panoramica generale e la correzione di bozze. Per la pagina Scrittura della tua prima app Electron, verrà creata una guida passo passo coerente con punti di inizio e di fine chiari e verranno rimosse le informazioni ridondanti (ad esempio due blocchi di codice simili nella sezione Sviluppo di Electron in pillole e Prova questo esempio).
Risultati: guide introduttive riviste e facili da seguire su come iniziare a utilizzare le applicazioni Electron.
SETTIMANA 3
Questa settimana sarà dedicata a: 1. miglioramenti della pagina Architettura dell'applicazione. Ciò include: - la riscrittura delle informazioni esistenti nella sezione Processi principale e di rendering per renderla più semplice e intuitiva per chi legge per la prima volta - l'aggiunta di una rappresentazione visiva dell'architettura, il modo in cui i processi sono collegati, il modo in cui comunicano e le loro differenze fondamentali. Esempi di immagini: Uno, Due, Tre (di bassa qualità). 2. Unificazione delle informazioni su tutte le funzionalità che puoi aggiungere alla tua applicazione Electron. Ciò include la riscrittura delle guide in modo che abbiano un insieme unificato di istruzioni su come installare/abilitare una funzionalità, oltre a un esempio del funzionamento della funzionalità. Inoltre, verrà creata una nuova pagina (riepilogativa) che elenca tutte le funzionalità disponibili per l'utilizzo. Le istruzioni unificate potrebbero avere il seguente aspetto: - Panoramica - Esempio: - Esempio di codice - Esempio visivo (se possibile)
- semplificazione della pagina Distribuzione delle applicazioni. Sono inclusi: a. l'unione del pacchettizzazione delle applicazioni alla guida alla distribuzione delle applicazioni b. la suddivisione dei metodi di distribuzione in automatici e manuali c. l'utilizzo di electron-forge come esempio di distribuzione automatica d. l'utilizzo delle informazioni su asar dalla pagina Pacchettizzazione delle applicazioni e la descrizione della copia dei file di origine e della creazione dell'archivio asar come esempi di distribuzione manuale. #### SETTIMANA 4 Questa settimana sarà dedicata alla ristrutturazione della directory della documentazione. Comprende:
1 - suddividere le guide esistenti in almeno tre categorie: a. Guida rapida b. Apprendimento delle nozioni di base c. Passaggi avanzati
La categoria Guida rapida conterrà i tutorial di base (installazione, configurazione, distribuzione) per creare una serie coerente di guide che consentiranno ai neofiti di iniziare da zero. Ogni guida deve contenere link alle guide precedenti/successive della serie.
La struttura potrebbe avere il seguente aspetto: 1. Prerequisiti 2. Installa Electron 3. Crea un'applicazione di base. 4. Pacchettizza/distribuisci l'applicazione
Dopo aver completato la sezione Guida rapida, l'utente conoscerà le nozioni di base sul funzionamento delle applicazioni Electron e avrà un'applicazione Electron distribuibile completamente funzionante.
La categoria Nozioni di base contiene le guide volte a rafforzare le conoscenze su Electron ed estendere l'applicazione creata nelle sezioni della guida rapida. Queste guide includono: - Architettura dell'applicazione - Aggiunta di funzionalità all'app - Boilerplate e interfacce a riga di comando
La categoria Passaggi avanzati contiene guide più avanzate finalizzate alla configurazione e al perfezionamento dell'applicazione Electron: - Test e debug - Accessibilità - Sicurezza - Aggiornamenti
2 - Ridurre il numero di pagine della documentazione. La versione attuale della documentazione presenta un certo grado di sovrapposizione dei contenuti e istruzioni non classificate. Ad esempio: - Installazione e installazione di Electron nella sezione Scrittura della tua prima app - Imballaggio dell'applicazione e Imballaggio dell'app in un file nella sezione Distribuzione dell'applicazione - Istruzioni non classificate nelle categorie In dettaglio e Avanzate: Suggerimento: sposta i seguenti documenti su GitHub ed escludili dalla documentazione principale. Questi documenti sono specifici per le linee guida di sviluppo di Electron e il repository di origine è il primo posto in cui cercarli: - Sviluppo di Electron - Sviluppo di Chromium - Sviluppo di V8 - Problemi in Electron - Patch in Electron - Pull request - Struttura della directory del codice sorgente - Test - Stile di programmazione
L'idea principale della riduzione è sbarazzarsi di un numero eccessivo di guide disponibili, unire i pezzi del puzzle delle informazioni sparsi e offrire ai neofiti una versione della documentazione di Electron più strutturata, facile da navigare e user-friendly.
SETTIMANE 5-7
La quinta settimana sarà dedicata alla preparazione di un modello (un modo) per integrare electron-api-demos nella documentazione principale. Questo modello potrebbe avere il seguente aspetto: 1. Nella documentazione principale, nella sezione "Aggiunta di funzionalità all'app", crea le categorie rappresentate in electron-api-demos 2. Esaminando ciascuna delle categorie, trasferisci gli esempi di demo alla documentazione principale: - I sample di codice possono essere presi dal codice sorgente o dalla descrizione della funzionalità corrispondente nell'applicazione - Ogni esempio trasferito deve essere seguito dalla descrizione associata - Ogni esempio secondario (ad esempio, la finestra di dialogo Errore come elemento secondario delle finestre di dialogo Utilizza il sistema) deve essere trasferito sotto l'elemento principale
NOTA 1: esistono esempi sia in electron-api-demos sia nella documentazione principale (ad esempio, scorciatoie da tastiera, trascinamento e rilascio). In questo caso, l'esempio di electron-api-demos deve avere la priorità e l'esempio nella documentazione principale deve essere ignorato.
NOTA 2: molti esempi nell'applicazione electron-api-demos hanno un'anteprima della demo dal vivo della funzionalità descritta. Questa funzionalità verrà ignorata fino all'integrazione di Electron Fiddle nelle settimane 9-10.
- Aggiorna la pagina che elenca tutte le funzionalità disponibili per l'utilizzo (creata durante la terza settimana) rispettando la nuova gerarchia di esempi.
Le settimane 6 e 7 saranno dedicate al trasferimento degli esempi di electron-api-demos alla documentazione principale in base al modello descritto sopra. Come passaggio finale, il repository electron-api-demos deve essere eliminato o ritirato.
SETTIMANE 8-10
La settimana 8 sarà dedicata alla preparazione di un modello (un modo) per integrare Electron Fiddle nella documentazione principale. Questa iniziativa è già stata lanciata (controlla i dettagli nel problema 20442) dal team di Electron insieme ai volontari della community, ma richiede una corretta finalizzazione.
Per procedere con gli esempi di Fiddle, il modello di base potrebbe avere il seguente aspetto: 1. Scegli un esempio dalla documentazione principale (ad esempio la guida rapida). A questo punto, la documentazione dovrebbe contenere anche esempi di electron-api-demos. 2. Ricrea l'esempio in Electron Fiddle (utilizzando il codice di esempio o il codice sorgente come punto di partenza); 3. Salva il Fiddle localmente in una cartella. 4. Sposta l'esempio in /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * L'elenco degli esempi completati è descritto nella sezione "Elenco di demo" del problema. 5. Aggiungi il pulsante "Avvia in Fiddle" come descritto nel commento iniziale del problema 2848.
Le settimane 9 e 10 saranno dedicate all'integrazione degli esempi di electron-api-demos (che sono già stati convertiti in Fiddle) nella documentazione principale in base al modello descritto sopra.
SETTIMANA 11
Questa settimana sarà interamente dedicata alla finalizzazione del progetto di scrittura dopo la corretta migrazione del repository elettronica-api-demos e dei campioni di Electron Fiddle. Sono inclusi: - verificare che tutti gli esempi di codice esistenti abbiano il pulsante "Avvia in Fiddle" - verificare che tutti gli esempi di codice esistenti funzionino correttamente come Fiddle - verificare che la documentazione principale non faccia più riferimento al repository electron-api-demos
SETTIMANA 12
Finalizzazione del lavoro completato. Controlli di accettazione.