Runbook de TI: como documentar procedimentos operacionais que qualquer tecnico consegue seguir

Por que runbook não é documentação decorativa

Toda equipe de TI tem aquele procedimento que só uma pessoa sabe executar. O restart do serviço que precisa de uma ordem específica, a rotina de fechamento mensal que exige três sistemas abertos ao mesmo tempo, o failover do link que ninguém testa há oito meses. Quando essa pessoa entra de férias, adoece ou pede demissão, o conhecimento sai junto. O runbook existe justamente para transformar conhecimento tácito em procedimento executável por qualquer técnico com o nível de acesso adequado.

A diferença entre um runbook e uma documentação genérica está na finalidade. Documentação explica como o sistema funciona. Runbook diz exatamente o que fazer, em que ordem, e como confirmar que deu certo. Um bom runbook não pressupõe que quem lê entende a arquitetura por trás — pressupõe apenas que a pessoa tem as credenciais e sabe usar o terminal ou o console. Essa distinção muda completamente a forma de escrever.

O teste prático é simples: entregue o runbook para um técnico que nunca executou aquele procedimento e observe. Se ele parar para perguntar algo, o runbook tem uma lacuna. Se ele executar do início ao fim sem interrupções e chegar ao resultado esperado, o documento cumpre a função. Runbook que precisa de tradução oral não é runbook — é anotação pessoal.

A anatomia de um runbook que funciona

Um runbook completo tem seis blocos obrigatórios. Cada bloco resolve um tipo específico de falha na execução, e omitir qualquer um deles cria um ponto onde o técnico trava.

• Identificação e escopo — nome do procedimento, sistema afetado, quando executar e quando NÃO executar. O critério negativo é tão importante quanto o positivo.
• Pré-requisitos — acessos necessários (com nome exato do grupo ou perfil), ferramentas instaladas, janela de manutenção exigida, aprovações prévias.
• Impacto e comunicação — quem fica sem serviço durante a execução, por quanto tempo, quem precisa ser avisado antes e depois.
• Passos numerados — cada passo com uma ação única e um resultado verificável.
• Critério de sucesso — o que precisa estar verdadeiro no final para o procedimento ser considerado concluído.
• Rollback — como desfazer, e até que ponto o desfazer ainda é possível.

O bloco de pré-requisitos é o mais negligenciado e o que mais gera retrabalho. Um procedimento que exige acesso de administrador de domínio precisa dizer isso na primeira linha, não descobrir no passo 7. O mesmo vale para dependências de horário: se a rotina só pode rodar fora do expediente porque derruba a sessão dos usuários, isso é pré-requisito, não observação de rodapé.

O bloco de rollback separa runbook maduro de rascunho. Nem todo procedimento é reversível, e está tudo bem — mas o documento precisa dizer explicitamente onde fica o ponto de não retorno. "A partir do passo 5, o snapshot é consolidado e não há volta" é uma informação que muda a postura de quem executa.

Como escrever passos que não deixam margem

Passo bom tem uma ação e uma verificação. Passo ruim tem três ações e nenhuma verificação. A regra prática é: se o passo contém a palavra "e" ligando dois verbos de ação, provavelmente são dois passos.

Compare as duas formulações abaixo. A primeira é o que aparece na maioria das documentações internas; a segunda é o que um técnico consegue seguir sob pressão, às 22h, sem ninguém para perguntar.

Ruim: "Pare o serviço, faça o backup e aplique a atualização."

Bom: "Passo 3. Pare o serviço: net stop AppService. Verificar: sc query AppService deve retornar STATE: STOPPED. Se retornar STOP_PENDING por mais de 60s, siga para o passo 3b."

Três elementos fazem a diferença: o comando exato (não "pare o serviço", mas o comando literal que pode ser copiado), a verificação objetiva (uma saída específica que confirma o resultado) e o desvio para o caso de exceção previsível. Esse terceiro elemento é o que evita a ligação às 23h perguntando "e agora?".

Evite linguagem condicional vaga. "Verifique se está tudo certo" não é verificação. "Confirme que o contador de erros no Event Viewer está em zero nos últimos 5 minutos" é. Sempre que possível, a verificação deve produzir um valor comparável — um status, um número, uma mensagem exata. Quando o resultado depende de julgamento humano, o runbook precisa definir o critério de julgamento, não delegar.

Ordem também é conteúdo. Numere os passos sequencialmente e use subnumeração (3a, 3b) apenas para desvios de exceção, nunca para passos normais. Isso permite que duas pessoas conversando por telefone se refiram ao mesmo ponto sem ambiguidade — algo que importa muito durante um incidente real.

Padronização: template único e versionamento

Runbooks escritos em formatos diferentes por pessoas diferentes acabam não sendo usados. O técnico precisa aprender uma estrutura nova a cada documento, e o custo cognitivo derruba a adoção. A solução é um template único, aplicado sem exceção, mesmo quando parece excessivo para procedimentos simples.

O template deve viver em um repositório versionado — Git, SharePoint com histórico, ou o wiki interno da empresa, desde que registre quem alterou o quê e quando. Runbook em arquivo Word na pasta compartilhada é o padrão que mais falha: ninguém sabe qual é a versão vigente, e correções feitas na cópia local de alguém nunca chegam ao restante da equipe.

1. Data da última validação no cabeçalho — não a data de criação, mas a data em que alguém executou o procedimento e confirmou que ainda funciona.
2. Responsável pela manutenção — uma pessoa nomeada, não "equipe de infraestrutura".
3. Ciclo de revisão — trimestral para procedimentos críticos, semestral para o restante.
4. Registro de execuções — quem rodou, quando, e se encontrou divergência entre o documento e a realidade.

O registro de execuções é o mecanismo que mantém o runbook vivo. Toda vez que alguém executa e encontra uma diferença — o botão mudou de lugar, o comando ganhou um parâmetro novo, o servidor foi migrado —, essa divergência precisa virar uma correção no documento na mesma sessão. Runbook desatualizado é pior que runbook inexistente: gera confiança falsa e leva o técnico a executar o passo errado com convicção.

Vale também classificar os runbooks por criticidade. Procedimentos que afetam produção, envolvem dados de clientes ou têm ponto de não retorno merecem revisão mais frequente e, idealmente, um teste de mesa periódico — alguém lê e executa em ambiente controlado para validar que o documento ainda descreve a realidade.

Erros comuns que inutilizam o documento

O erro mais frequente é escrever para si mesmo. Quem conhece o sistema omite o óbvio, e o óbvio para o autor é exatamente o que trava o leitor. Frases como "acesse o console de sempre" ou "use a credencial padrão" presumem contexto que o técnico novo não tem. Nomeie o console, informe onde a credencial está armazenada, dê o caminho completo.

O segundo erro é o excesso de explicação. Runbook não é treinamento. Se o procedimento precisa de contexto arquitetural para ser entendido, esse contexto vai num documento separado, linkado no cabeçalho. Misturar os dois produz um texto longo que ninguém lê durante um incidente — e incidente é justamente quando o runbook mais importa.

O terceiro erro é não testar. Runbook escrito e nunca executado é hipótese, não procedimento. A validação mínima é pedir para outra pessoa executar em ambiente de homologação, sem ajuda, e anotar cada ponto de hesitação. Cada hesitação é um defeito do documento, não do executor.

• Screenshots sem data — a interface muda e a imagem vira armadilha. Prefira descrição textual do caminho de menu.
• Senhas ou tokens no corpo do texto — aponte para o cofre de credenciais, nunca embuta o segredo.
• Links internos quebrados para outros documentos que foram movidos ou renomeados.
• Ausência de critério de sucesso — o técnico executa tudo e não sabe se terminou.

Transformando runbooks em operação previsível

Documentar procedimentos é o primeiro passo; o ganho real aparece quando o runbook vira base para automação. Um procedimento descrito com comandos exatos e verificações objetivas está a poucos passos de virar um script. Não por acaso, as equipes que automatizam melhor são as que documentaram bem antes — a automação apenas codifica o que o runbook já tornou explícito.

O indicador de maturidade é o tempo médio de resolução por procedimento e a variação desse tempo entre técnicos diferentes. Quando dois profissionais com níveis distintos de senioridade executam a mesma rotina em tempos parecidos, a padronização está funcionando. Quando a diferença é grande, o runbook ainda depende de conhecimento que só um deles tem.

Na Duk Informática & Cloud, esse é o padrão que aplicamos na operação dos ambientes que gerenciamos. Com mais de 18 anos de estrada e mais de 550 empresas atendidas, aprendemos que previsibilidade não vem de ter o técnico mais experiente disponível — vem de ter o procedimento certo escrito, testado e ao alcance de qualquer pessoa da equipe. Como Microsoft Gold Partner, mantemos runbooks versionados para as rotinas de infraestrutura, backup, Microsoft 365 e segurança dos nossos clientes, com ciclo de revisão definido e registro de cada execução.

Se a sua operação ainda depende de conhecimento concentrado em poucas pessoas, o caminho começa pelos três procedimentos mais críticos e menos documentados. Escreva-os no template, peça para alguém que nunca os executou seguir o passo a passo, e corrija cada ponto de hesitação. Repita o ciclo. Em poucos meses, a diferença entre um plantão tranquilo e uma madrugada perdida passa a ser uma questão de documento aberto na tela, não de sorte na escala.