Introdução
Um codelab é um tutorial interativo escrito na sintaxe Markdown. Publicamos nossos codelabs em blocklycodelabs.dev. Os codelabs 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 está seguindo e executando o código conforme lê.
Criar 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 ótimo?
Um ótimo codelab é focado e legível. Ele informa claramente ao usuário o que ele vai criar e o que vai aprender, além de ensinar o usuário a escrever e entender o código para concluir uma tarefa específica.
Processo
Se você tiver uma ideia para um codelab, compartilhe com a gente fazendo uma solicitação de recurso no repositório de amostras do Blockly. Inclua uma descrição do que você quer ensinar e do que vai criar no codelab. Vamos discutir e refinar a ideia. Em seguida, você pode escrever e enviar uma solicitação de envio para ela. Depois da revisão, um membro da equipe do Blockly vai publicar o conteúdo.
Dicas de escrita
O restante desta página é um conjunto de dicas e perguntas para orientar você na criação de um codelab.
Confira Redação técnica 1 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 ele está tentando aprender?
Configuração
- Qual é a configuração mínima necessária para o usuário executar 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: [Title goes here]
- Explicação/motivação
- Exemplo de código
- Resultados esperados
- (Opcional) Mais explicações
- …
- Etapa 10: [Title goes here]
- 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ê chegar a 20, considere dividi-las em dois codelabs.
Estilo de escrita
- Use um estilo de escrita informal.
- Use títulos para deixar a organização clara.
- Use listas com marcadores para dividir textos longos.
- 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.