Como documentar automações: escreve a regra de negócio, não os cliques

Documentar os cliques não serve: isso já a ferramenta guarda

Quando alguém procura como documentar automações, acaba quase sempre por fazer o mesmo: capturas de ecrã do editor, um passo a passo de que módulo vem a seguir a qual e uma descrição de cada nó. Uma tarde inteira de trabalho. E é trabalho deitado fora, porque estás a copiar à mão a única coisa que a ferramenta já sabe sozinha.

O Make, o n8n, o Zapier ou o Power Automate mostram-te o grafo do fluxo em dois cliques: o que o dispara, o que vem a seguir, que campo se mapeia com qual. Isso está vivo e sempre atualizado. A tua captura não: caduca na primeira vez que o fabricante muda um menu de sítio ou troca a cor de um botão, e a partir daí documenta uma interface que já não existe.

O efeito secundário é pior do que o desfasamento. Uma documentação que parece velha deixa de ser lida, e assim que deixa de ser lida toda a gente assume que o resto também mente. Um manual que ninguém abre é exatamente tão útil como não ter manual, com o agravante de ainda ter de ser mantido.

O grafo diz-te o que o fluxo faz. Nunca te diz porquê. E o porquê não está em lado nenhum a não ser na cabeça de quem o montou.

O bus factor: se só uma cabeça sabe o porquê, esse é o teu risco real

O bus factor de um sistema é quantas pessoas se podem ir embora antes desse sistema ficar sem ninguém capaz de o perceber. Em automação de empresa o número é quase sempre um. Uma pessoa montou o fluxo, essa pessoa sabe porque é que o limite são 48 horas e não 72, e é a essa pessoa que se liga quando acontece alguma coisa estranha.

Não é preciso um autocarro. Bastam umas férias, uma mudança de equipa, uma baixa longa ou uma proposta melhor. E o incómodo é que o fluxo não se parte —isso seria fácil de detetar—: continua a correr pontualmente todos os dias. O que se parte é a capacidade de o mudar.

Nota-se muito antes de chegar o desastre. Os sintomas de um bus factor igual a um são sempre os mesmos cinco:

• Ninguém toca no fluxo. As alterações colam-se por fora, num fluxo novo, porque mexer no original mete medo.
• Cada mudança de negócio abre uma discussão arqueológica. «E isto porque é que está assim?». Ninguém sabe, por isso fica como está.
• Aparece um duplicado. Alguém monta outro fluxo que faz quase o mesmo, porque começar do zero saía mais barato do que perceber o que já lá estava.
• Não se consegue explicar uma decisão. Chega a pergunta de um cliente ou de um auditor sobre porque é que o sistema fez o que fez, e a resposta honesta é que não se sabe.
• O fluxo congela. Quando a pessoa sai, fica ligado e ninguém se atreve nem a mudá-lo nem a desligá-lo.

Repara que nenhum destes cinco sintomas se cura com uma captura de ecrã do editor.

A única coisa que há para escrever: a regra de negócio

Uma regra de negócio é a decisão humana que o fluxo toma em teu nome enquanto ninguém está a olhar. Não é «se o campo estado for igual a pendente, enviar email». É: «ao cliente que está há 48 horas sem responder insistimos uma vez, porque o contrato tipo promete resposta em dois dias úteis e não queremos falhar; exceto se for conta grande, e aí é a pessoa de contas que avisa em vez do sistema».

Todo o resto —o módulo, a ordem, o mapeamento de campos— é implementação. Muda no dia em que mudares de ferramenta e não acontece nada. A regra sobrevive à ferramenta: se amanhã migrares do Zapier para o n8n, a regra é a única coisa que tens de levar contigo, e é precisamente a única que não está escrita em lado nenhum.

Porquê essa condição e não outra

Cada número que aparece num fluxo saiu de algum lado: um compromisso de serviço, uma promessa comercial, um requisito legal ou —o mais habitual— uma reunião de há dois anos. Escreve qual. «48 horas porque é o prazo que o contrato tipo promete» é uma condição revisível no dia em que o contrato mudar. «48 horas» sem mais é um número intocável que ninguém se vai atrever a mexer.

Que exceção cobre

Os ramos estranhos de um fluxo quase nunca são um capricho: são cicatrizes. Aquele filtro que descarta as encomendas abaixo de certo valor está ali porque um dia entrou uma leva de testes e sujou a faturação. Escrever a cicatriz evita as duas coisas que acontecem quando não está escrita: que alguém tire o filtro por «limpeza» e o incidente volte, ou que ninguém se atreva a mexer-lhe mesmo que o motivo original tenha desaparecido há anos.

A quem avisa e o que acontece se ninguém responder

O que rebenta em produção normalmente não é a lógica: é o final em aberto. Um fluxo que escala para uma pessoa tem de dizer para quem, por que canal, com que prazo — e o que faz se essa pessoa não responder. Se a resposta for «fica à espera indefinidamente», isso também é uma decisão e tem de ficar escrita, porque no dia em que uma encomenda estiver uma semana pendurada alguém vai perguntar se é uma avaria ou o desenho.

Colados à regra vão três dados que não são negócio mas perdem-se com a mesma facilidade: o dono —uma pessoa com nome e apelido, não um departamento—, as credenciais que usa —que conta, de quem e com que permissões— e os sistemas em que mexe, separando o que lê do que escreve. O que escreve é o que te pode desarrumar o CRM numa terça-feira à tarde.

É aqui que este guia roça a governação e o controlo da automação sem ser a mesma coisa. A governação põe permissões, auditoria e travão de mão: é controlo. Isto é conhecimento. Podes ter controlo perfeito sobre um fluxo que ninguém percebe — e então a única coisa que consegues fazer com precisão é desligá-lo.

A ficha mínima: uma página por fluxo, oito campos

Se a ficha não couber numa página, não vai ser mantida. É esse o critério de desenho inteiro. Oito campos, respostas de duas linhas, e está feito:

1. O que produz. A saída concreta, não a categoria. «Deixa uma linha por encomenda na folha da logística», não «gere encomendas».
2. Dono. Uma pessoa. Se o nome que lá está já não trabalha cá, a ficha está caducada e isso vê-se num relance.
3. Regra de negócio. O porquê de cada condição, com a sua origem. É o campo longo e o único que justifica a ficha existir.
4. Exceções. Que caso raro cobre cada ramo e que incidente o pôs ali.
5. A quem avisa. Pessoa ou fila, canal, prazo, e o que acontece se ninguém responder.
6. Credenciais. Que conta usa, de quem é e com que permissões. Nenhum segredo dentro da ficha, obviamente: só o nome da conta.
7. Sistemas em que mexe. O que lê e o que escreve, em duas listas separadas.
8. O que NÃO faz. O limite explícito do fluxo.

O oitavo campo é o que ninguém põe e o que mais discussões poupa. «Não mexe em faturas já emitidas», «não escreve no ERP», «não responde fora de horas». Sem esse campo, cada incidente começa com vinte minutos a descartar se foi este fluxo — e passado um ano, toda a gente lhe atribui poderes que nunca teve.

Onde vive a ficha para não envelhecer

Aqui está a parte incómoda, e digo-a sem rodeios: se a ficha viver num Confluence, num Notion ou numa pasta do Drive à parte, vai envelhecer. Não é culpa da ferramenta, é a distância. Quem muda o fluxo está dentro do editor, com pressa, a arranjar alguma coisa; se atualizar a ficha significar abrir outro separador, procurar a página e editar, não o vai fazer. Uma vez não acontece nada. À décima alteração, a ficha mente.

A ficha tem de viver onde vive o fluxo. Três sítios que funcionam mesmo, do menos ao mais esforço: o campo de descrição ou as notas do próprio cenário —o Make, o n8n, o Power Automate e quase todos têm um—, onde há menos fricção porque já estás lá dentro; um README junto ao JSON exportado se versionares os fluxos num repositório, o que ainda te oferece histórico de alterações; e uma nota fixada no canal onde o fluxo publica, quando a saída dele é uma notificação.

O wiki não desaparece: muda de papel. Deixa de ser onde vive a documentação e passa a ser o índice —que fluxos existem, quem é o dono de cada um e onde está a sua ficha—. Isso aguenta, porque é uma lista curta que muda pouco. O que não aguenta é o detalhe longe do sítio onde se lhe mexe.

Atualizar a ficha faz parte de mudar o fluxo, não é uma tarefa à parte

Toda a documentação que morre morre da mesma maneira: alguém a escreve num esforço pontual e, a partir daí, mantê-la é «uma tarefa» que compete com o trabalho a sério. Compete e perde, sempre, porque nunca é urgente e nunca há ninguém à espera dela.

A única forma de isso não acontecer é tirá-la da lista de tarefas e metê-la dentro da definição de terminado. Mudar um fluxo não está terminado quando o fluxo funciona: está terminado quando o fluxo funciona e a ficha diz o que ele faz agora. São dois minutos se a ficha estiver a um clique, e são dois minutos que só aparecem se ninguém os tratar como opcionais. O resto —lembretes trimestrais, campanhas de documentação, auditorias internas— é teatro com calendário.

É assim que fecha o círculo com o resto do cluster. Um fluxo com ficha e com dono é um fluxo que se pode manter vivo sem adivinhar nada, e é um fluxo que não acaba como uma daquelas automações zombie que ninguém desliga porque ninguém sabe o que se parte. Documentar não mantém nem retira: faz com que manter e retirar sejam decisões em vez de apostas. Se estás a montar tudo isto de raiz, o mapa completo está no guia de automatizar com IA.