Introdução
Um codelab é um tutorial interativo escrito na sintaxe de markdown. Publicamos nossos codelabs em blocklycodelabs.dev (em inglês), que usam uma combinação 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á acompanhando e executando o código durante a leitura.
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 se deparar com o mesmo problema.
O que torna um codelab ótimo?
Um ótimo codelab é focado e legível. Ela informa claramente ao usuário o que ele criará e o que aprenderá, além de orientar o usuário a escrever e entender o código para concluir uma tarefa específica.
Processo
Se você tem 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 o que criará no codelab. Discutiremos e refinaremos a ideia. Em seguida, você pode escrevê-lo e enviar uma solicitação de envio para ele. Depois que ele for revisado, um membro da equipe do Blockly o publicará.
Dicas de escrita
O restante desta página é um conjunto de dicas e perguntas para orientar você na criação de um codelab.
Consulte A escrita técnica One (em inglês) para uma introdução rápida à escrita técnica.
Público-alvo
- Quem é o leitor-alvo?
- O que o seu público-alvo já sabe 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, você poderá publicar o código inicial
e o código concluído
no diretório examples.
Estrutura
Como acontece com qualquer escrita, comece com um esboço. Esta é uma boa estrutura para a maioria dos codelabs:
- Introdução
- Conteúdo
- O que você vai criar
- Algumas informações importantes
- Instruções de configuração
- Primeira etapa: [O título vai aqui]
- Explicação/motivação
- Exemplo de código
- Resultados esperados
- (Opcional) Mais explicações
- ...
- Etapa 10: [O título vai 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 10 etapas, se você chegar a 20 etapas, considere dividi-las em dois codelabs.
Estilo de escrita
- Use um estilo de escrita conversacional.
- Use títulos para esclarecer a organização.
- Use listas com marcadores para quebrar paredes de textos.
- Use imagens e gifs!
Estilo de código
- Você pode escrever no ES5, ES6 ou TypeScript, mas informar ao leitor qual é no início.
- Siga o Guia de estilo do Google.