Como documentar decisões técnicas para que não se percam

Há 6 meses decidimos não usar um determinado plugin de cache num projeto. Discutimo-lo numa reunião, chegámos a um consenso e seguimos em frente.

Na semana passada, um programador acabado de entrar perguntou porque é que não o usávamos e propôs instalá-lo. Passei 20 minutos a explicar algo que já tínhamos decidido.

Não é o fim do mundo, mas esses 20 minutos não voltam. Multiplica isso por cada decisão técnica de um projeto de vários meses e por cada pessoa que entra. O resultado são dias inteiros de conversas repetidas.

Documentar decisões técnicas não é burocracia desnecessária. É um seguro contra o esquecimento. E o esquecimento sai caro.

Porque é que as decisões se perdem (e porque é que isso dói)

Nas equipas de desenvolvimento, as decisões técnicas têm uma vida média curta. Os motivos são previsíveis:

Rotação da equipa. Quem tomou a decisão já não está. Quem chega não tem o contexto e parte do princípio de que a decisão atual não tem razão de ser.

Distância no tempo. Há 8 meses decidiste não usar React porque o projeto não o justificava. Agora cresceu e alguém propõe migrar. E tu ficas na dúvida: foi uma decisão consciente ou é que, na altura, ninguém na equipa dominava React?

Mudança de contexto. As decisões tomam-se com a informação disponível em cada momento. Essa informação muda, e a decisão deveria ser revista. Mas, se não sabes o que a motivou, não consegues saber se a mudança é relevante.

Comunicação informal. “Falámos disso no Slack”, “ficou decidido na reunião”, “isso sabe o João”. O Slack perde-se no scroll infinito, as reuniões não são gravadas e o João foi para outra empresa.

O que é um bom registo de decisões

Na Baqueiro usamos um formato simples a que chamamos Decision Record (DR). Não é uma invenção nossa: baseia-se nos Architecture Decision Records (ADR), uma prática bastante difundida no setor, simplificada para equipas pequenas.

Cada DR tem 5 secções:

1. Contexto. Que problema estávamos a resolver? Que restrições tínhamos (orçamento, prazos, conhecimento da equipa)? Que alternativas avaliámos?

2. Decisão. O que escolhemos? Tem de ser concreta: “vamos usar Laravel com Laravel Nova para o painel de administração”, não “uma solução moderna”.

3. Consequências. O que ganhamos e o que perdemos? Todas as decisões têm contrapartidas, e um bom DR é honesto sobre elas.

4. Data e participantes. Quando foi tomada e quem participou? Assim sabes a quem perguntar se surgirem dúvidas.

5. Estado. Está em vigor, foi substituída ou revista? As decisões mudam, e o DR tem de o refletir.

Onde guardamos os Decision Records

O formato importa, mas a localização importa mais. Um DR num documento que ninguém abre não serve para nada.

Guardamo-los em 3 sítios, consoante a sua natureza:

Decisões de um projeto concreto: no próprio repositório, numa pasta /docs/decisions/. Junto ao código e versionadas com ele. É a primeira coisa que vês ao entrar no projeto.

Decisões de arquitetura transversais: na wiki da equipa, organizadas por área (frontend, backend, infraestrutura), porque afetam todos os projetos.

Decisões sobre ferramentas e processos: no Notion, junto aos procedimentos internos. Por exemplo, porque usamos Figma e não Sketch.

A regra é simples: a documentação tem de estar onde alguém a procuraria naturalmente no momento em que tem a dúvida.

Quando criar um Decision Record

Não documentamos tudo, porque seria paralisante. Criamos um DR quando:

• A decisão é difícil de reverter (framework, base de dados, arquitetura de serviços).
• Esperamos que alguém a ponha em causa mais tarde (novas entradas no projeto, crescimento).
• Há alternativas razoáveis que outros poderiam propor, e queremos deixar claro porque as pusemos de lado.
• A decisão afeta o trabalho de outras pessoas (processos, ferramentas partilhadas).

Não criamos DR para decisões triviais (usar snake_case nas tabelas), óbvias (usar HTTPS) nem para aquilo que o próprio código já explica.

Um exemplo de Decision Record

Este DR baseia-se num dos nossos projetos, anonimizado e ligeiramente simplificado:

DR-014: Não vamos usar Elasticsearch para a pesquisa de produtos

Data: setembro de 2024

Participantes: direção técnica, responsável de backend, responsável de sistemas

Contexto: O cliente tem cerca de 3000 produtos e quer pesquisa avançada (filtros combinados, ordenação por relevância). A equipa de backend propôs implementar Elasticsearch para melhorar o desempenho e as capacidades de pesquisa.

Decisão: Vamos usar a pesquisa nativa do MySQL com índices otimizados. Não vamos implementar Elasticsearch nesta fase.

Razões:

• Um catálogo de 3000 produtos está folgadamente dentro do que o MySQL com bons índices resolve bem.
• O Elasticsearch complicaria o deploy: exige um servidor adicional ou um serviço gerido.
• A equipa não tem experiência a operar Elasticsearch em produção, e o risco de problemas de infraestrutura supera hoje os benefícios.
• O cliente não tem orçamento para a infraestrutura adicional.

Consequências:

• Pesquisamos com índices FULLTEXT do MySQL e consultas otimizadas. O desempenho é aceitável para o volume atual.
• Não vamos ter pesquisa tolerante a erros de digitação nem um cálculo de relevância avançado.
• Se o catálogo ultrapassar os 10 000 produtos ou o cliente precisar de uma pesquisa mais sofisticada, será preciso reconsiderar.

Estado: Em vigor. Rever se o catálogo ultrapassar os 10 000 produtos ou se o cliente pedir funcionalidades de pesquisa que o MySQL não consiga oferecer.

Uns meses depois, alguém perguntou: “porque é que não usamos Elasticsearch?”. Enviámos-lhe a ligação para o DR-014. A conversa durou 3 minutos, não 30. A decisão manteve-se porque o contexto não tinha mudado.

Como manter os Decision Records atualizados

Um DR desatualizado é pior do que não ter nenhum, porque dá uma falsa segurança sobre uma decisão que já não se aplica.

A nossa regra: sempre que alguém põe em causa uma decisão documentada, o respetivo DR é revisto.

• Se se mantém, acrescenta-se uma linha: “revisto em [data], contexto sem alterações”.
• Se muda, marca-se como substituído e cria-se um novo que explique o contexto atual e tenha uma ligação para o anterior.

Assim vai-se formando um histórico que tem valor por si só: vês como a arquitetura evoluiu e porquê. Para integrar alguém novo no projeto, vale ouro. É a mesma lógica que aplicamos às automatizações, onde a falta de documentação transforma qualquer alteração em arqueologia, como explicamos em o custo oculto das automatizações mal documentadas.

Objeções habituais

“Não temos tempo para isto.”

Escrever um DR leva de 10 a 20 minutos. Discutir a mesma decisão 3 vezes porque não ficou por escrito leva horas. É matemática.

“O código já é documentação suficiente.”

O código explica o que se fez, não porquê. E o porquê é precisamente o que se esquece e o que mais custa reconstruir.

“Ninguém lê a documentação.”

Se não é lida, o problema é onde está ou como está organizada, não a documentação em si. Um DR no repositório aparece naturalmente quando alguém trabalha nessa parte do código.

“As decisões mudam constantemente, acabaríamos com um caos de documentos desatualizados.”

Se algo muda constantemente, não devia ser um DR. Os DR são para decisões com consequências duradouras. O que muda todas as semanas é configuração, não arquitetura.

Perguntas frequentes

O cliente deve ver os Decision Records?

Depende. Os que afetam decisões de negócio, sim. Os puramente internos, não. Para clientes com perfil técnico mantemos uma versão resumida.

O que acontece se alguém ignorar um DR e fizer o que lhe apetece?

Os DR não são leis, são o registo de um consenso. Se alguém quer mudar uma decisão, discute-se e atualiza-se o DR. Ignorá-lo é um problema de cultura de equipa, não de documentação.

Precisamos de uma ferramenta especial?

Não. Um ficheiro Markdown no repositório funciona perfeitamente. O importante é o hábito, não a ferramenta. Se queres começar hoje, cria a pasta, escreve o DR da última decisão que a tua equipa tenha discutido 2 vezes e numera-o como DR-001.

Conclusão

Documentar decisões técnicas não é uma desculpa para não as tomar, nem burocracia para justificar o que já existe. É respeito pelo tempo futuro: o teu, quando não te lembrares porque fizeste algo; o da tua equipa, quando alguém entrar num projeto já começado; e o de quem herdar o código daqui a uns anos.

Se a tua equipa perde tempo a discutir decisões que já foram tomadas, ou se entras em projetos sem perceber porque estão feitos assim, talvez te falte um sistema de Decision Records. Na Baqueiro podemos ajudar-te a implementá-lo sem complicar a tua forma de trabalhar. Conta-nos como trabalha hoje a tua equipa.