- A maioria dos tutoriais de software omite detalhes importantes ou inclui suposições ocultas que não correspondem às expectativas do leitor, o que o impede de reproduzir o processo
- Seguindo algumas regras simples, escrever um tutorial excelente é mais fácil do que parece
Regras
- Escrever para iniciantes
- Criar um título que prometa um resultado claro
- Explicar o objetivo na introdução
- Mostrar o resultado final antecipadamente
- Escrever snippets de código que possam ser copiados e colados
- Usar flags longas nos comandos
- Separar valores personalizados da lógica reutilizável
- Reduzir o esforço do leitor
- Escrever de modo que o código permaneça sempre funcional
- Ensinar apenas um tópico
- Priorizar clareza em vez de enfeites
- Minimizar dependências
- Especificar claramente os nomes dos arquivos
- Usar títulos consistentes e descritivos
- Comprovar que a solução funciona
- Vincular um exemplo completo
Escrever para iniciantes
- O erro mais comum em tutoriais é explicar conceitos de nível iniciante com termos de nível especialista. A maioria das pessoas que procura tutoriais é iniciante.
- Elas podem não ser iniciantes em programação, mas são iniciantes no domínio que querem aprender
- Escreva para iniciantes e evite o uso de termos de nível especialista
- Evite termos difíceis e escreva em linguagem simples que o leitor consiga entender
- Por exemplo, em um tutorial de React, ofereça uma explicação como "criar uma página web simples com React" em vez de "JSX transpilation"
Criar um título que prometa um resultado claro
- O título deve comunicar de forma concreta o que o leitor poderá aprender com o tutorial
- Evite títulos vagos ou ambíguos e descreva claramente o resultado esperado
- Ex.: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"
Explicar o objetivo na introdução
- Quando o leitor clica no tutorial, isso significa que ele tem interesse no que você tem a dizer. Mas você ainda precisa convencê-lo a continuar lendo
- Há duas coisas que o leitor quer saber
- Eu deveria me interessar por essa tecnologia?
- Se me interessar, este tutorial é adequado para mim?
- Na introdução, explique de forma concisa a importância da tecnologia e a utilidade do tutorial
- Forneça informações úteis para despertar o interesse do leitor e evite descrições vagas
- Ex.: um tutorial de Docker deve explicar claramente qual problema o Docker resolve e qual resultado pode ser esperado
Mostrar o resultado final antecipadamente
- O mais cedo possível, mostre uma demo ou captura de tela do que o leitor vai criar com o tutorial
- Mostrar o resultado final no começo do tutorial deixa o objetivo claro
- Ex.: forneça uma captura de tela do produto final, da UI, um exemplo de funcionamento etc.
Escrever snippets de código que possam ser copiados e colados
- Escreva de forma que o leitor possa copiar facilmente o código, colá-lo no editor ou no terminal e executá-lo
- Remova elementos desnecessários, como o caractere de prompt de terminal
$
- Use flags não interativas para simplificar os comandos e
&& para interromper em caso de falha
Usar flags longas nos comandos
- Em comandos, use flags longas com significado claro em vez de flags curtas, para que iniciantes também consigam entender facilmente
Separar valores personalizados da lógica reutilizável
- Separe claramente, no código, os valores que o usuário deve modificar daqueles trechos que não devem ser alterados
- Use variáveis de ambiente para definir valores personalizados e melhorar a legibilidade do código
Reduzir o esforço do leitor
- Respeite o tempo do leitor para aumentar as chances de ele gostar do tutorial
- Substitua tarefas tediosas por snippets de comando
- Ex.: resolva com comandos em vez de pedir que o leitor edite arquivos manualmente
Escrever de modo que o código permaneça sempre funcional
- O código de exemplo deve ser sempre executável e permanecer funcional mesmo nas etapas intermediárias
- Código incorreto ou exemplos que não funcionam causam confusão ao leitor
Ensinar apenas um tópico
- O tutorial deve ser escrito em torno de um único tema, sem misturar tecnologias não relacionadas
- Por exemplo, não adicione tecnologias de IA desnecessárias a um tutorial que explica uma funcionalidade de busca
Priorizar clareza em vez de enfeites
- O leitor não se importa se um aplicativo de demonstração parece bonito
- Minimize CSS e elementos de design desnecessários e concentre-se no conceito principal
- Em vez de exemplos complexos, use código simples para transmitir o conceito com clareza
Minimizar dependências
- Minimize as dependências que o leitor precisa instalar para aumentar a acessibilidade do tutorial
- Especifique claramente as dependências obrigatórias e indique versões específicas
Especificar claramente os nomes dos arquivos
- Oriente com precisão quais caminhos de arquivo e conteúdos o leitor deve modificar
- Por exemplo, em vez de "adicionar a configuração no arquivo config", forneça o caminho completo do arquivo e um código específico mostrando exatamente qual linha deve ser editada
Usar títulos consistentes e descritivos
- Use headings estruturados para que o leitor possa percorrer o tutorial com facilidade
- Use títulos para estruturar o tutorial e escreva-os de forma a refletir uma organização lógica
- Mantenha consistência no formato, no ponto de vista e no tempo verbal dos títulos
Comprovar que a solução funciona
- Se o tutorial ensina a instalar ferramentas ou integrar vários componentes, mostre como usar o resultado
- Mostre visualmente ao leitor o resultado do funcionamento das ferramentas instaladas e integradas
- Por exemplo, mostre a página de sucesso do nginx e explique como verificar isso pela URL
Vincular um exemplo completo
- Vincule um repositório com todo o código do tutorial para que seja possível verificar o fluxo completo
- Divida o código de cada etapa em branches separadas do git para que o leitor possa acompanhar cada etapa
11 comentários
Para referência
Isso merece um marcador!
Que bom texto.
Recentemente segui o tutorial do dagster. Achei que ele foi muito bem feito.
https://courses.dagster.io/
Dei uma olhada no tutorial do Dagster e ele é muito bom.
O tutorial do Django tem um conteúdo ótimo, mas é longo demais, então eu particularmente não curto muito. Acho que seria melhor se fosse dividido em partes menores.
Há também o Django como exemplo de um tutorial bem feito: https://docs.djangoproject.com/en/5.1/intro/tutorial01/
Usar uma linguagem simples & mostrar o resultado final primeiro.
Às vezes há tutoriais que, em vez de mostrar o uso básico e sem graça de um framework, querem mostrar o quanto esse framework é incrível.
Eu realmente detesto quando entro no Get started e o que está marcado como tutorial básico de uso é um documento de 10 páginas.
Todo mundo é impressionante demais...
https://tanstack.com/table/latest/docs/introduction
https://github.com/tmux/tmux/wiki/Getting-Started