Introduzione
Un codelab è un tutorial interattivo scritto in sintassi Markdown. Pubblichiamo i nostri codelab all'indirizzo blocklycodelabs.dev. I codelab utilizzano un mix di linguaggio naturale, esempi di codice e screenshot per creare un'esperienza tutorial più interessante. L'utente target di un codelab segue ed esegue il codice mentre legge.
Scrivere un codelab è un ottimo modo per contribuire alla community. È un modo per condividere le tue conoscenze e semplificare la vita al prossimo sviluppatore che si imbatterà nello stesso problema.
Quali sono le caratteristiche di un ottimo codelab?
Un codelab efficace è mirato e leggibile. Indica chiaramente all'utente cosa creerà e cosa imparerà e lo guida nella scrittura e nella comprensione del codice per completare un'attività specifica.
Processo
Se hai un'idea per un codelab, puoi comunicarcela inviando una richiesta di funzionalità nel repository blockly-samples. Includi una descrizione di ciò che vuoi insegnare e di ciò che creerai nel codelab. Discuteremo e perfezioneremo l'idea. Dopodiché puoi scriverlo e inviare una richiesta di pull. Una volta superata la revisione, un membro del team di Blockly la pubblicherà.
Suggerimenti per la scrittura
Il resto di questa pagina è un insieme di suggerimenti e domande per guidarti nella scrittura di un codelab.
Dai un'occhiata a Technical Writing One per una rapida introduzione alla redazione tecnica.
Pubblico
- Chi è il lettore target?
- Cosa sanno già dell'utilizzo di Blockly?
- Che cosa sta cercando di imparare?
Configurazione
- Qual è la configurazione minima richiesta all'utente per eseguire il tuo codice?
Se può esserti utile, puoi pubblicare il codice iniziale
e il codice completato
nella directory examples.
Struttura
Come per qualsiasi testo, inizia con una bozza. Questa è una buona struttura per la maggior parte dei codelab:
- Introduzione
- Obiettivi didattici
- Cosa creerai
- Informazioni importanti
- Istruzioni di configurazione
- Passaggio 1: [Titolo]
- Spiegazione/motivazione
- Esempio di codice
- Risultati previsti
- (Facoltativo) Ulteriori spiegazioni
- …
- Passaggio 10: [Titolo qui]
- Riepilogo
- Che cosa hai imparato
- Cosa hai creato
- Risorse aggiuntive
- Link al codice completato (se disponibile)
Anche se puoi avere più di dieci passaggi, se ne raggiungi venti, ti consigliamo di suddividerli in due codelab.
Stile di scrittura
- Utilizza uno stile di scrittura colloquiale.
- Utilizza le intestazioni per rendere chiara l'organizzazione.
- Utilizza elenchi puntati per suddividere i blocchi di testo.
- Utilizza immagini e GIF.
Stile di codice
- Puoi scrivere in ES5, ES6 o TypeScript, ma indica al lettore quale linguaggio utilizzi all'inizio.
- Segui la guida di stile di Google.