Todo mundo já abandonou um tutorial no passo 4. Você seguiu tudo certinho, mas o comando não roda, a tela não bate com o print, e você fecha a aba. A culpa quase nunca é sua: é de quem escreveu. Dá pra fazer diferente, e não é difícil.
Antes de escrever, responda duas perguntas
Para quem é isso e o que a pessoa vai conseguir fazer depois? Se você não responde as duas em uma frase, o tutorial vai divagar. "Para um dev júnior que nunca subiu um container, que ao final terá a app rodando em localhost:3000." Pronto. Agora você sabe o que cortar e onde parar.
Um caminho só, e ele funciona
Tutorial não é documentação de referência. Escolha UM caminho, o mais direto, e ignore os desvios. Nada de "se você usa macOS, faça X; se Windows, Y; se prefere yarn...". Cada bifurcação dobra a chance de a pessoa se perder. Ramificações viram notas de rodapé ou outro artigo.
Mostre onde a pessoa vai chegar
Logo no começo, mostre o resultado. Um print da tela final, o JSON de resposta, o site no ar. Isso dá contexto e motiva: a pessoa sabe que o esforço tem destino. Sem isso, cada passo é um salto no escuro.
Comando que dá pra copiar sem pensar
Comando bom é comando que a pessoa cola e roda. Nada de docker run <sua-imagem> com placeholder que ninguém sabe preencher. Dê o comando completo:
docker run -d -p 3000:3000 --name minha-app node:20
Use blocos de código, um comando por bloco quando fizer sentido, e mostre a saída esperada logo abaixo. Se a pessoa não vê o mesmo output, ela sabe na hora que algo saiu do trilho.
Erre no lugar do leitor
Você já sabe onde as pessoas tropeçam: porta ocupada, permissão negada, variável de ambiente esquecida. Antecipe. Depois do passo arriscado, um bloco curto: "Se aparecer EADDRINUSE, a porta 3000 já está em uso; troque para 3001." Isso salva a pessoa de abrir três abas no Stack Overflow e desistir no meio.
O teste final: faça você mesmo, do zero
O tutorial só está pronto quando você segue ele numa máquina limpa, sem pular nada, sem usar o que já está instalado na sua. Container novo, pasta nova, copiando e colando cada comando como se fosse a primeira vez. É aqui que aparecem os passos que você achava óbvios e ninguém mais acha.
Um bom tutorial não é o mais completo. É o que a pessoa termina. Escreva pra chegar ao fim.
