Introdução
Um codelab é um tutorial interativo escrito na sintaxe Markdown. Publicamos nossos codelabs em blocklycodelabs.dev. Eles usam uma mistura de linguagem natural, exemplos de código e capturas de tela para criar uma experiência de tutorial mais interessante. O usuário-alvo de um codelab acompanha e executa o código enquanto lê.
Escrever um codelab é uma ótima maneira de contribuir com a comunidade. É uma maneira de compartilhar seu conhecimento e facilitar a vida do próximo desenvolvedor que encontrar o mesmo problema.
O que faz um codelab ser excelente?
Um bom codelab é focado e fácil de ler. Ele informa claramente ao usuário o que ele vai criar e aprender, além de orientar a escrita e a compreensão do código para concluir uma tarefa específica.
Processo
Se você tiver uma ideia para um codelab, envie uma solicitação de recurso no repositório blockly-samples. Inclua uma descrição do que você quer ensinar e do que será criado no codelab. Vamos discutir e refinar a ideia. Em seguida, escreva e envie uma solicitação de envio. Depois de passar por análise, um membro da equipe do Blockly vai publicar.
Dicas de escrita
O restante desta página é um conjunto de dicas e perguntas para orientar você na criação de um codelab.
Confira Technical Writing One (em inglês) para uma introdução rápida à redação técnica.
Público-alvo
- Quem é o leitor-alvo?
- O que eles já sabem sobre o uso do Blockly?
- O que eles estão tentando aprender?
Configuração
- Qual é a configuração mínima necessária para que o usuário execute seu código?
Se for útil, publique o código inicial
e o código concluído
no diretório examples.
Estrutura
Como em qualquer texto, comece com um esboço. Esta é uma boa estrutura para a maioria dos codelabs:
- Introdução
- O que você vai aprender
- O que você vai criar
- O que você precisa saber
- Instruções de configuração
- Etapa 1: [O título vai aqui]
- Explicação/motivação
- Exemplo de código
- Resultados esperados
- (Opcional) Mais explicações
- …
- Etapa 10: [Insira o título aqui]
- Resumo
- O que você aprendeu
- O que você criou
- Outros recursos
- Link para o código concluído (se disponível)
Embora seja possível ter mais de dez etapas, se você estiver chegando a vinte, considere dividir em dois codelabs.
Estilo de escrita
- Use um estilo de escrita conversacional.
- Use títulos para deixar a organização clara.
- Use listas com marcadores para dividir blocos de texto.
- Use imagens e GIFs.
Estilo de código
- Você pode escrever em ES5, ES6 ou TypeScript, mas informe ao leitor qual é no início.
- Siga o guia de estilo do Google