Scrivere un codelab efficace

Introduzione

Un codelab è un tutorial interattivo scritto con la sintassi di markdown. Pubblichiamo i nostri codelab su blocklycodelabs.dev. I codelab utilizzano una combinazione di linguaggio naturale, esempi di codice e screenshot per creare un'esperienza di 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 facilitare la vita al prossimo sviluppatore che riscontra lo stesso problema.

Quali sono le caratteristiche di un codelab efficace?

Un codelab efficace è mirato e leggibile. Indica chiaramente all'utente cosa creerà e cosa apprenderà e accompagnerà l'utente attraverso la scrittura e la comprensione del codice per completare un'attività specifica.

Processo

Se hai un'idea per un codelab, puoi informarci inviando una richiesta di funzionalità nel repository blockly-samples. Includi una descrizione di ciò che vuoi insegnare e di ciò che creerai nel codelab. Approfondiremo e perfezioneremo l'idea. Quindi puoi annotarlo e inviare una richiesta di pull. Al termine della revisione, un membro del team di Blockly lo pubblicherà.

Suggerimenti per la scrittura

Il resto di questa pagina contiene una serie di suggerimenti e domande per guidarti nella scrittura di un codelab.

Consulta La scrittura tecnica per una rapida introduzione alla scrittura tecnica.

Pubblico

  • Chi è il lettore di destinazione?
  • Cosa sanno già sull'uso di Blockly?
  • Che cosa cercano di imparare?

Configurazione

  • Qual è la configurazione minima richiesta all'utente per eseguire il tuo codice?

Se è utile, puoi pubblicare il codice iniziale e il codice completato nella directory examples.

Struttura

Come per qualsiasi tipo di testo, inizia con un contorno. Questa è una buona struttura per la maggior parte dei codelab:

  • Introduzione
    • Obiettivi didattici
    • Cosa creerai
    • Cosa devi sapere
    • Istruzioni sulla configurazione
  • Passaggio uno: [il titolo va qui]
    • Spiegazione/motivazione
    • Esempio di codice
    • Risultati previsti
    • (Facoltativo) Ulteriori spiegazioni
  • ...
  • Passaggio 10: [il titolo va 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 raggiungi venti passaggi potresti suddividere il programma in due codelab.

Stile di scrittura

  • Utilizza uno stile di scrittura colloquiale.
  • Utilizza le intestazioni per chiarire l'organizzazione.
  • Utilizza elenchi puntati per separare i muri di testo.
  • Usa immagini e GIF.

Stile codice