Como documentar decisións técnicas para que non se perdan

Hai 6 meses decidimos non usar certo plugin de caché nun proxecto. Discutímolo nunha reunión, chegamos a un consenso e seguimos adiante.

A semana pasada, un programador recén incorporado preguntou por que non o usabamos e propuxo instalalo. Pasei 20 minutos explicando algo que xa decidiramos.

Non é a fin do mundo, pero eses 20 minutos non volven. Multiplícao por cada decisión técnica dun proxecto de varios meses e por cada persoa que se incorpora. O resultado son días enteiros de conversas repetidas.

Documentar decisións técnicas non é burocracia innecesaria. É un seguro contra o esquecemento. E o esquecemento sae caro.

Por que se perden as decisións (e por que doe)

Nos equipos de desenvolvemento, as decisións técnicas teñen unha vida media curta. Os motivos son previsibles:

Rotación do equipo. Quen tomou a decisión xa non está. Quen chega non ten o contexto e dá por feito que a decisión actual non ten razón de ser.

Distancia no tempo. Hai 8 meses decidiches non usar React porque o proxecto non o xustificaba. Agora medrou e alguén propón migrar. E ti dubidas: foi unha decisión consciente ou é que daquela ninguén no equipo dominaba React?

Cambio de contexto. As decisións tómanse coa información dispoñible en cada momento. Esa información cambia, e a decisión debería revisarse. Pero se non sabes que a motivou, non podes saber se o cambio é relevante.

Comunicación informal. “Falámolo en Slack”, “quedou na reunión”, “iso sábeo Xoán”. Slack pérdese no scroll infinito, as reunións non se gravan e Xoán marchou a outra empresa.

Que é un bo rexistro de decisións

En Baqueiro usamos un formato sinxelo que chamamos Decision Record (DR). Non é un invento noso: baséase nos Architecture Decision Records (ADR), unha práctica bastante estendida no sector, simplificada para equipos pequenos.

Cada DR ten 5 seccións:

1. Contexto. Que problema estabamos a resolver? Que restricións tiñamos (orzamento, prazos, coñecemento do equipo)? Que alternativas valoramos?

2. Decisión. Que escollemos? Ten que ser concreta: “usaremos Laravel con Laravel Nova para o panel de administración”, non “unha solución moderna”.

3. Consecuencias. Que gañamos e que perdemos? Toda decisión ten contrapartidas, e un bo DR é honesto sobre elas.

4. Data e participantes. Cando se tomou e quen participou? Así sabes a quen preguntar se xorden dúbidas.

5. Estado. Está vixente, substituída ou revisada? As decisións cambian, e o DR ten que reflectilo.

Onde gardamos os Decision Records

O formato importa, pero a localización importa máis. Un DR nun documento que ninguén abre non serve de nada.

Gardámolos en 3 sitios, segundo a súa natureza:

Decisións dun proxecto concreto: no propio repositorio, nun cartafol /docs/decisions/. Xunto ao código e versionadas con el. É o primeiro que ves ao entrar no proxecto.

Decisións de arquitectura transversais: na wiki do equipo, organizadas por área (frontend, backend, infraestrutura), porque afectan a todos os proxectos.

Decisións sobre ferramentas e procesos: en Notion, xunto aos procedementos internos. Por exemplo, por que usamos Figma e non Sketch.

A regra é simple: a documentación ten que estar onde alguén a buscaría de forma natural no momento de ter a dúbida.

Cando crear un Decision Record

Non documentamos todo, porque sería paralizante. Creamos un DR cando:

• A decisión é difícil de reverter (framework, base de datos, arquitectura de servizos).
• Agardamos que alguén a cuestione máis adiante (incorporacións ao proxecto, crecemento).
• Hai alternativas razoables que outros poderían propor, e queremos deixar claro por que as descartamos.
• A decisión afecta ao traballo doutras persoas (procesos, ferramentas compartidas).

Non creamos DR para decisións triviais (usar snake_case nas táboas), obvias (usar HTTPS) nin para o que o propio código xa explica.

Un exemplo de Decision Record

Este DR está baseado nun dos nosos proxectos, anonimizado e lixeiramente simplificado:

DR-014: Non usaremos Elasticsearch para a busca de produtos

Data: setembro de 2024

Participantes: dirección técnica, responsable de backend, responsable de sistemas

Contexto: O cliente ten uns 3.000 produtos e quere busca avanzada (filtros combinados, ordenación por relevancia). Desde backend propúxose implementar Elasticsearch para mellorar o rendemento e as capacidades de busca.

Decisión: Usaremos a busca nativa de MySQL con índices optimizados. Non implementaremos Elasticsearch nesta fase.

Razóns:

• Un catálogo de 3.000 produtos está folgadamente dentro do que MySQL con bos índices resolve ben.
• Elasticsearch complicaría o despregamento: require un servidor adicional ou un servizo xestionado.
• O equipo non ten experiencia operando Elasticsearch en produción, e o risco de problemas de infraestrutura supera hoxe os beneficios.
• O cliente non ten orzamento para a infraestrutura adicional.

Consecuencias:

• Buscamos con índices FULLTEXT de MySQL e consultas optimizadas. O rendemento é aceptable para o volume actual.
• Non teremos busca tolerante a erros tipográficos nin un cálculo de relevancia avanzado.
• Se o catálogo supera os 10.000 produtos ou o cliente necesita unha busca máis sofisticada, haberá que reconsideralo.

Estado: Vixente. Revisar se o catálogo supera os 10.000 produtos ou se o cliente pide funcións de busca que MySQL non pode ofrecer.

Uns meses despois, alguén preguntou: “por que non usamos Elasticsearch?”. Pasámoslle a ligazón ao DR-014. A conversa durou 3 minutos, non 30. A decisión mantívose porque o contexto non cambiara.

Como manter os Decision Records ao día

Un DR obsoleto é peor que non ter ningún, porque dá unha falsa seguridade sobre unha decisión que xa non se aplica.

A nosa regra: cada vez que alguén cuestiona unha decisión documentada, revísase o seu DR.

• Se se mantén, engádese unha liña: “revisado o [data], contexto sen cambios”.
• Se cambia, márcase como substituído e créase un novo que explique o contexto actual e ligue co anterior.

Así vaise formando un historial que ten valor por si mesmo: ves como evolucionou a arquitectura e por que. Para incorporar alguén novo ao proxecto, é ouro. É a mesma lóxica que aplicamos ás automatizacións, onde a falta de documentación converte calquera cambio en arqueoloxía, como explicamos en o custo oculto das automatizacións mal documentadas.

Obxeccións habituais

“Non temos tempo para isto.”

Escribir un DR leva de 10 a 20 minutos. Discutir a mesma decisión 3 veces porque non quedou por escrito leva horas. Son matemáticas.

“O código xa é documentación suficiente.”

O código explica que se fixo, non por que. E o porqué é xusto o que se esquece e o que máis custa reconstruír.

“Ninguén le a documentación.”

Se non se le, o problema é onde está ou como está organizada, non a documentación en si. Un DR no repositorio aparece de forma natural cando alguén traballa nesa parte do código.

“As decisións cambian constantemente, acabariamos cun caos de documentos obsoletos.”

Se algo cambia constantemente, non debería ser un DR. Os DR son para decisións con consecuencias duradeiras. O que cambia cada semana é configuración, non arquitectura.

Preguntas frecuentes

Debería o cliente ver os Decision Records?

Depende. Os que afectan a decisións de negocio, si. Os puramente internos, non. Para clientes con perfil técnico mantemos unha versión resumida.

Que pasa se alguén ignora un DR e fai o que lle parece?

Os DR non son leis, son o rexistro dun consenso. Se alguén quere cambiar unha decisión, discútese e actualízase o DR. Ignoralo é un problema de cultura de equipo, non de documentación.

Necesitamos unha ferramenta especial?

Non. Un ficheiro Markdown no repositorio funciona perfectamente. O importante é o hábito, non a ferramenta. Se queres comezar hoxe, crea o cartafol, escribe o DR da última decisión que o teu equipo discutise 2 veces e numérao como DR-001.

Conclusión

Documentar decisións técnicas non é unha escusa para non tomalas, nin burocracia para xustificar o que xa hai. É respecto polo tempo futuro: o teu, cando non lembres por que fixeches algo; o do teu equipo, cando alguén entre nun proxecto xa comezado; e o de quen herde o código dentro duns anos.

Se o teu equipo perde tempo discutindo decisións que xa se tomaron, ou se entras en proxectos sen entender por que están feitos así, quizais che falta un sistema de Decision Records. En Baqueiro podemos axudarche a implantalo sen complicar a túa forma de traballar. Cóntanos como traballa hoxe o teu equipo.