Progetto Electron

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

Riepilogo del progetto

Organizzazione open source:

Elettrone

Technical writer:

Mister Oro

Nome progetto:

Flusso tutorial elettronico

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 basate su Electron contiene quasi 900 voci e l'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 risiede nella sua semplice curva di apprendimento e nella bassa soglia di accesso: chiunque conosca JavaScript, HTML e stack CSS può creare la propria applicazione. Enormi tassi di crescita complessivi richiedono di creare tutorial e guide introduttive facili da comprendere e utilizzare.

L'obiettivo del progetto è portare fiducia ai costruttori di applicazioni che non hanno mai utilizzato il framework Electron e fornire loro un'esperienza coerente e semplificata nello sviluppo delle proprie applicazioni Electron da zero.

Problemi relativi al progetto

Di seguito è riportato un elenco dei problemi più cruciali relativi alla documentazione dei tutorial Electron: 1. Punto di partenza non chiaro e informazioni introduttive non intuitive sui passaggi di sviluppo delle applicazioni 2. Informazioni sparse e ridondanti relative al processo di sviluppo delle applicazioni 3. Istruzioni disordinate della guida per iniziare senza un'unica fonte attendibile

PROPOSTA DI PROGETTO

In base all'obiettivo del progetto e ai problemi descritti sopra, di seguito è riportato un elenco dei miglioramenti proposti: 1. Aggiorna le guide esistenti. Per rendere i primi passaggi fluidi e coerenti, è opportuno aggiornare i seguenti documenti con un passaggio graduale dal più semplice al più complesso: - Ambiente di sviluppo - Scrittura della tua prima app Electron - Aggiunta di funzionalità all'app (creazione di una pagina di riepilogo) - Packaging e distribuzione dell'app 2. Ristrutturare la directory della documentazione. Per mostrare ai nuovi sviluppatori ciò che è essenziale per iniziare e quelli che possono essere considerati ulteriori passaggi, la pagina dei documenti dovrebbe avere una suddivisione visiva e contestuale dei passaggi per rendere attiva la prima applicazione il più rapidamente possibile. La ristrutturazione include anche indicazioni sui possibili passaggi successivi. 3. Organizza e unifica la documentazione per lo sviluppo delle applicazioni. Tutte le funzionalità devono avere un insieme unificato di istruzioni su come installarla/attivarla, come iniziare rapidamente, come lavorare con un'app dopo il primo lancio e come distribuirla. 4. Includi il repository elettronici-api-demos nella documentazione. Il repository elettronici-api-demos contiene un insieme di esempi che mostrano come aggiungere caratteristiche alla tua applicazione Electron. Queste informazioni devono essere incluse nella guida all'aggiunta di funzionalità alla tua app per garantire la coerenza con un'unica strategia per i contenuti basata su una fonte attendibile. 5. Integrare 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 "Launch in Fiddle" ai blocchi di codice.

Cronaca

Periodo di revisione della domanda - Familiarizza con la community e le persone con cui lavorare. Scopri le guide e le best practice per i contributi della community. Pubblica i primi contributi. Legami della community - Esplora la community. Ispeziona lo stato attuale della documentazione di Electron. Identifica i punti deboli. Settimana 1 - Allineati ai mentori sui traguardi e i risultati finali del progetto Settimana 2 - Rivedere l'ambiente di sviluppo e scrivere le pagine della tua prima app Electron Settimana 3 - Rivedere l'architettura delle applicazioni, aggiungere funzionalità all'app, pacchettizzazione e pagine di distribuzione dell'app. Creare una pagina di riepilogo con un elenco di funzionalità che possono essere aggiunte all'app Settimana 4 - Ristrutturare la directory della documentazione Settimana 5 - Preparare un modello di come elettronica-api-demos verrà integrata nella documentazione principale Settimane 6 - 7 - Eseguire la migrazione del repository elettronici-api-demos Settimana 8 - Preparare un modello per l'integrazione di Electron Fiddle nella documentazione principale. Scrivi il primo campione. Settimane 9-10 - Integrazione di Electron Fiddle nella documentazione principale Settimana 11 - Finalizzazione della struttura e delle pagine di documentazione principali dopo la migrazione del repository elettronici-api-demos e degli esempi di Electron Fiddle Settimana 12 - Valutazione dei risultati

ANALISI DETTAGLIATA DELLE TRAGUARDI

PERIODO DI REVISIONE DELLE APPLICAZIONI La prima parte del periodo sarà dedicata alla verifica dei canali e del codice sorgente della comunità e al contatto con le persone dedicate al progetto.

La seconda parte del periodo sarà dedicata alla verifica della cultura del contributo in generale, esaminando le guide ai contributi e le best practice. Questo sarà il momento dei primi contributi per vedere come funziona il flusso.

COLLEGAMENTO DELLA COMMUNITY

Questo tempo sarà dedicato a un esame più approfondito della cartella della documentazione e della relativa roadmap. In base a queste informazioni, sarà possibile identificare i punti deboli (ad es. le parti incomplete o mancanti) che possono essere migliorate. Crea richieste di pull (ove possibile) per colmare le lacune.

SETTIMANA 1 - SETTIMANA 2

La prima settimana sarà dedicata alla comunicazione con i mentori per allinearsi ai traguardi previsti e alla loro tempestiva consegna.

La seconda settimana riguarda la revisione dell'ambiente degli sviluppatori e la scrittura delle pagine della tua prima app Electron. La pagina Ambiente per gli sviluppatori includerà la riscrittura di una panoramica generale e una correzione di bozze. Per la pagina Scrivere la tua prima app Electron, sarà inclusa la creazione di una guida passo passo coerente con punti di inizio e di fine chiari, nonché la rimozione di informazioni ridondanti (come due blocchi di codice simili nella sezione Electron Development in a Nutshell e Provare questo esempio).

Risultati: guide introduttive riviste e facili da seguire su come avviare le applicazioni Electron.

SETTIMANA 3

Questa settimana sarà dedicata a: 1. Miglioramenti della pagina Architettura delle applicazioni. Ciò include: - riscrittura delle informazioni esistenti nella sezione Processi principali e del renderer per renderle più semplici e più intuitive per i nuovi lettori - Aggiunta di una rappresentazione visiva dell'architettura, del modo in cui i processi sono connessi, del modo in cui comunicano e della differenza fondamentale. Esempi di immagini: uno, due, tre (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 dispongano di un insieme unificato di istruzioni su come installare/attivare una funzionalità, oltre a un esempio di funzionamento. Inoltre, verrà creata una nuova pagina (riepilogo) con un elenco di tutte le funzionalità disponibili. Le istruzioni unificate potrebbero avere il seguente aspetto: - Panoramica - Esempio: - Esempio di codice - Esempio visivo (ove possibile)

1. della pagina Distribuzione delle applicazioni. Ciò include: a. Unione dell'Application Packaging nella guida alla distribuzione delle applicazioni b. Divisione dei metodi di distribuzione in automatici e manuali c. Prendendo l'elettron-forge come esempio di distribuzione automatica d. L'acquisizione di informazioni su asar dalla pagina Application Packaging e la descrizione della copia dei file sorgente e della creazione di un archivio asar come esempi di distribuzione manuale. #### SETTIMANA 4 Questa settimana sarà dedicata alla ristrutturazione della directory della documentazione. tra cui:

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 nuovi utenti di avviare una guida rapida 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. Pacchetti/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 Apprendimento delle nozioni di base conterrà le guide mirate 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 - Boilerplates e interfacce a riga di comando

La categoria Passaggi avanzati contiene guide più avanzate mirate alla configurazione e all'ottimizzazione della tua applicazione Electron: - Test e debug - Accessibilità - Sicurezza - Aggiornamenti

2 - Riducendo il numero di pagine di documentazione. La versione attuale della documentazione presenta un certo grado di contenuti sovrapposti e istruzioni senza categoria. Ad esempio: - Installazione e installazione di Electron nella scrittura della prima app - Presentazione e pacchettizzazione dell'app in un file all'interno della distribuzione dell'applicazione - Istruzioni senza categoria nelle categorie Dettaglio e Avanzato: Suggerimento: sposta i seguenti documenti in GitHub ed escludili dalla documentazione principale. Questi documenti sono specifici per le linee guida per lo sviluppo di Electron e il repository del codice sorgente è il primo posto in cui cercarli: - Sviluppo di Electron - Sviluppo di Chromium - Sviluppo V8 - Problemi relativi a Electron - Patch in Electron - Richieste di pull - Struttura della directory del codice sorgente - Test - Stile di codifica

L'idea principale della riduzione è quella di eliminare un numero oppressivo di guide disponibili, unendo insieme le informazioni sparse del puzzle e dando ai nuovi arrivati una versione più strutturata, facilmente navigabile e facile da usare della documentazione di Electron.

SETTIMANE 5 - 7

La quinta settimana sarà dedicata alla preparazione di un modello (un modo) di come l'integrazione di elettronici-api-demos nella documentazione principale. Il modello potrebbe avere il seguente aspetto: 1. Nella documentazione principale, nella sezione "Aggiunta di funzionalità alla tua app", crea le categorie rappresentate nell'oggetto elettronici-api-demos. 2. Esaminando ciascuna delle categorie, trasferisci gli esempi dimostrativi alla documentazione principale: - Gli esempi di codice possono essere recuperati 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 di errore come elemento secondario delle finestre di dialogo di sistema Utilizza) deve essere trasferito sotto la relativa descrizione principale

NOTA #1: esistono esempi che esistono sia in elettronici-api-demos che nella documentazione principale (ad esempio, scorciatoie da tastiera, trascinamento). In questo caso, l'esempio di elettronici-api-demos dovrebbe avere la priorità, mentre l'esempio nella documentazione principale deve essere ignorato.

NOTA 2: molti esempi nell'applicazione elettronici-api-demos includono un'anteprima della demo dal vivo della caratteristica o funzionalità descritta. Questa funzionalità verrà ignorata fino all'integrazione con Electron Fiddle nelle settimane 9-10.

1. Aggiorna la pagina che elenca tutte le funzionalità disponibili per l'uso (create durante la Settimana 3) rispettando la nuova gerarchia degli esempi.

Le settimane 6 e 7 saranno dedicate al trasferimento degli esempi di elettronici-api-demos nella documentazione principale secondo il modello descritto sopra. Come passaggio finale, il repository elettronici-api-demos deve essere eliminato o deprecato.

SETTIMANE 8 - 10

La settimana 8 sarà dedicata alla preparazione di un modello (un modo) di come Electron Fiddle verrà integrato nella documentazione principale. Questa iniziativa è già stata lanciata (per maggiori dettagli nel numero 20442) da Electron guys insieme a volontari della comunità, ma richiede un'adeguata messa a punto.

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 elettronici-api-demos; 2. Ricrea l'esempio in Electron Fiddle (utilizzando il codice di esempio o il codice sorgente come punto di partenza); 3. Salvare il violino localmente in una cartella; 4. Sposta l'esempio in /docs/fiddles/[CATEGORIA]/[SEZIONE]/[DEMO]. * L'elenco degli esempi completati è descritto nella sezione "Elenco delle demo" del problema. 5. Aggiungi il pulsante "Launch in Fiddle" (Avvia in violino) come descritto nel commento iniziale nel numero 2848.

Le settimane 9 e 10 saranno dedicate all'integrazione degli esempi di elettronici-api-demos (già convertiti in Fiddles) nella documentazione principale secondo il modello descritto sopra.

SETTIMANA 11

Questa settimana sarà dedicata al completamento del progetto di scrittura dopo la migrazione del repository elettronici-api-demos e degli esempi di Electron Fiddle. Ciò include: - 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 Fiddles - verificare che la documentazione principale non faccia più riferimento al repository elettronici-api-demos

SETTIMANA 12

Finalizzazione del lavoro completato. Controlli di accettazione.