Deixar a documentação de uma automação em um wiki que ninguém atualiza cria falsa confiança e faz o runbook falhar no dia do incidente, justamente quando mais se precisava dele

Ter a documentação de uma automação em um wiki costuma parecer proteção suficiente. Pedir a alguém que não conhece o sistema que siga o passo a passo, sem ajuda, revela um desgaste que a existência do documento nunca deixaria perceber isoladamente.

Deixar a documentação de uma automação em um wiki que ninguém atualiza cria falsa confiança e faz o runbook falhar no dia do incidente, justamente quando mais se precisava dele — porque a documentação envelhece mais rápido que o sistema, e instruções que citam comandos antigos ou serviços que já não existem ensinam a equipe a ignorar o que está escrito.

Por que um wiki completo parece proteção suficiente

A existência de um documento dá a sensação de que o conhecimento está salvo, e ninguém testa o documento até o dia em que alguém que não conhece o sistema precisa seguir o passo a passo. Nesse momento, sob pressão, descobre-se que metade dos passos já não corresponde à realidade, e o tempo de resposta ao incidente depende de quem ainda lembra como as coisas funcionam.

O que caracteriza uma documentação que acompanha a automação

Uma documentação genuinamente eficaz fica perto do código ou da configuração e é atualizada na mesma mudança que altera a automação. Isso tem relação direta com "Automação que só uma pessoa entende não é automação. É dependência disfarçada" — os dois casos apontam pro mesmo princípio de fundo: o conhecimento sobre uma automação precisa existir fora da cabeça de uma pessoa e de forma utilizável, seja evitando a dependência de quem a construiu, seja garantindo que o que está escrito corresponda ao que está rodando.

Por que a documentação envelhece mais rápido que o sistema

Atualizá-la depende de alguém lembrar de fazer isso, enquanto o sistema muda por necessidade. O que não é atualizado na hora da mudança tende a não ser atualizado nunca, e um passo a passo escrito há seis meses provavelmente cita um comando, um endereço ou um serviço que já foi trocado, o que faz a equipe aprender a desconfiar do documento e a recorrer à memória de quem sabe.

Como perceber se o runbook já está desatualizado

A forma prática de perceber isso é pedir a alguém que não conhece a automação que siga o passo a passo em um ambiente de teste, sem ajuda. Se travar em um comando, link ou tela que mudou, o runbook já está desatualizado, e quanto mais travamentos, maior a falsa confiança que ele estava criando.

Um exemplo prático

Uma empresa mantém um runbook detalhado pra reiniciar uma integração de cobrança. Num incidente de madrugada, a pessoa de plantão, que não construiu a integração, segue o documento e esbarra em um painel que foi trocado e em um comando que já não existe, perdendo horas. Depois, a equipe passa a guardar o runbook junto da configuração, a atualizá-lo na mesma alteração e a fazer um teste trimestral em que alguém de fora o executa.

O ponto central

Antes de considerar uma automação documentada, vale testar se uma pessoa que nunca a viu consegue operá-la só com o documento. Runbook desatualizado é pior que nenhum — ele dá a segurança de um mapa que já não corresponde ao terreno.