Scrivere un codelab

Introduzione

Un codelab è un tutorial interattivo scritto in sintassi Markdown. Pubblichiamo i nostri codelab all'indirizzo 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 di destinazione di un codelab segue il codice e lo esegue mentre legge.

Scrivere un codelab è un ottimo modo per dare il proprio contributo alla community. È un modo per condividere le tue conoscenze e semplificare la vita al prossimo sviluppatore che si imbatte nello stesso problema.

Cosa rende un codelab eccellente?

Un ottimo codelab è mirato e leggibile. Indicano chiaramente all'utente cosa deve sviluppare e cosa deve imparare e lo guidano 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. Ne discuteremo e la perfezioneremo. Dopodiché puoi scrivere la richiesta e inviarne una pull. Una volta superata la revisione, un membro del team di Blockly la pubblicherà.

Suggerimenti per la scrittura

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

Consulta Technical Writing One per una rapida introduzione alla scrittura tecnica.

Pubblico

  • Chi è il lettore di destinazione?
  • Che cosa sanno già sull'utilizzo di Blockly?
  • Che cosa stanno cercando di imparare?

Configurazione

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

Se utile, puoi pubblicare il codice di avvio e il codice completato nella directory examples.

Struttura

Come per qualsiasi testo, inizia con una traccia. Questa è una buona struttura per la maggior parte dei codelab:

  • Introduzione
    • Obiettivi didattici
    • Cosa creerai
    • Informazioni importanti
    • Istruzioni di configurazione
  • Passaggio 1: [qui il titolo]
    • Spiegazione/motivazione
    • Esempio di codice
    • Risultati previsti
    • (Facoltativo) Ulteriori spiegazioni
  • …
  • Passaggio 10: [Title goes here]
  • Riepilogo
    • Che cosa hai imparato
    • Che cosa hai creato
    • Risorse aggiuntive
    • Link al codice completato (se disponibile)

Sebbene sia possibile avere più di dieci passaggi, se raggiungi i venti dovresti considerare la possibilità di suddividerli in due codelab.

Stile di scrittura

  • Utilizza uno stile di scrittura colloquiale.
  • Utilizza le intestazioni per rendere chiara l'organizzazione.
  • Utilizza gli elenchi puntati per suddividere i testi in blocchi.
  • Utilizza immagini e GIF.

Stile di codice