Documentação que não inventa
A técnica de fontes fechadas: como fazer o assistente escrever só o que está nas evidências e marcar explicitamente o que não encontrou.
Peça a documentação de um serviço e você recebe um texto excelente. Bem estruturado, completo, com exemplos de comando. Metade dos comandos não existe no seu projeto.
- Aplicar a técnica de fontes fechadas para eliminar invenção.
- Fazer o assistente marcar lacunas em vez de preenchê-las.
- Validar cada comando antes de publicar.
A causa é a mesma da aula 1.1: quando falta informação, a saída mais provável é a mais comum no material de treino. Um comando de deploy genérico é altamente provável; o seu comando de deploy específico, não. E documentação errada é pior que documentação ausente, porque ausência gera pergunta e erro gera confiança.
A técnica que resolve isso tem três partes: fornecer as fontes, proibir o que estiver fora delas, e exigir marcação explícita das lacunas.
Escreve a documentação de deploy do serviço de pedidos.
Vem um documento plausível com kubectl apply, variáveis de ambiente inventadas e um passo de rollback que não existe.
Escreva o runbook de deploy usando SOMENTE as fontes abaixo. Regras: - Nenhuma afirmação pode vir do seu conhecimento geral. - Tudo que não estiver nas fontes: escreva NÃO INFORMADO e siga. - Ao final, liste as perguntas que eu preciso responder para completar. FONTES: [1] .github/workflows/deploy.yml: [cole] [2] Makefile: [cole] [3] Mensagem do último incidente de rollback: [cole]
Vem um documento menor, com lacunas visíveis — e as lacunas são exatamente o que ninguém tinha escrito ainda.
A diferença: O documento com dez NÃO INFORMADO é mais útil que o completo e inventado: ele vira uma lista de tarefas em vez de uma armadilha.
O que uma documentação boa responde
| Pergunta | Quem lê isso | Onde costuma faltar |
|---|---|---|
| Como faço a coisa mais comum? | Quem chegou hoje | Raramente falta |
| Por que foi decidido assim? | Quem vai mudar em 2027 | Falta quase sempre |
| O que não fazer? | Quem vai improvisar às 3h | Falta quase sempre |
| Como sei que deu certo? | Quem executou e está inseguro | Falta com frequência |
| O que fazer quando falha? | Quem está no incidente | Falta com frequência |
As quatro últimas linhas são o que separa documentação de tutorial. Nenhuma delas o assistente consegue inventar — todas dependem de fonte.
Um comando errado num runbook é lido por alguém sob pressão, durante um incidente, e executado sem revisão. É o pior contexto possível para um erro de documentação.
Regra sem exceção: todo comando de runbook é executado uma vez em ambiente seguro antes de o documento ser publicado. Se não deu para testar, o comando entra marcado como NÃO VALIDADO.
Como perceber: O runbook tem um comando que ninguém no time lembra de ter rodado.
Não é em escrever do zero — é em transformar: virar um histórico de pull requests em changelog, um conjunto de testes em descrição de comportamento, uma thread de incidente em post-mortem estruturado.
Em todos esses casos a fonte é rica e real, e o trabalho é de reorganização. É exatamente onde a invenção tem menos espaço.
- As fontes foram fornecidas e listadas no pedido.
- O documento marca NÃO INFORMADO em vez de preencher.
- Todo comando foi executado uma vez em ambiente seguro.
- O documento responde "por que" e "o que não fazer", não só "como".
- As perguntas em aberto viraram tarefas com responsável.
- Feche as fontes, proíba o conhecimento geral e exija que as lacunas apareçam marcadas.
Comentários e dúvidas
Inscreva-se grátis para comentar, tirar dúvidas, marcar seu progresso e emitir o certificado ao fim do curso.
Inscrever-se grátis com GoogleAinda não há comentários nesta aula.