Cómo documentar decisiones técnicas para que no se pierdan

Hace 6 meses decidimos no usar cierto plugin de caché en un proyecto. Lo discutimos en una reunión, llegamos a un consenso y seguimos adelante.

La semana pasada, un desarrollador recién incorporado preguntó por qué no lo usábamos y propuso instalarlo. Pasé 20 minutos explicando algo que ya habíamos decidido.

No es el fin del mundo, pero esos 20 minutos no vuelven. Multiplícalo por cada decisión técnica de un proyecto de varios meses y por cada persona que se incorpora. El resultado son días enteros de conversaciones repetidas.

Documentar decisiones técnicas no es burocracia innecesaria. Es un seguro contra el olvido. Y el olvido sale caro.

Por qué se pierden las decisiones (y por qué duele)

En los equipos de desarrollo, las decisiones técnicas tienen una vida media corta. Los motivos son previsibles:

Rotación del equipo. Quien tomó la decisión ya no está. Quien llega no tiene el contexto y da por hecho que la decisión actual no tiene razón de ser.

Distancia en el tiempo. Hace 8 meses decidiste no usar React porque el proyecto no lo justificaba. Ahora ha crecido y alguien propone migrar. Y tú dudas: ¿fue una decisión consciente o es que entonces nadie en el equipo dominaba React?

Cambio de contexto. Las decisiones se toman con la información disponible en cada momento. Esa información cambia, y la decisión debería revisarse. Pero si no sabes qué la motivó, no puedes saber si el cambio es relevante.

Comunicación informal. «Lo hablamos en Slack», «quedó en la reunión», «eso lo sabe Juan». Slack se pierde en el scroll infinito, las reuniones no se graban y Juan se fue a otra empresa.

Qué es un buen registro de decisiones

En Baqueiro usamos un formato sencillo que llamamos Decision Record (DR). No es un invento nuestro: se basa en los Architecture Decision Records (ADR), una práctica bastante extendida en el sector, simplificada para equipos pequeños.

Cada DR tiene 5 secciones:

1. Contexto. ¿Qué problema estábamos resolviendo? ¿Qué restricciones teníamos (presupuesto, plazos, conocimiento del equipo)? ¿Qué alternativas valoramos?

2. Decisión. ¿Qué elegimos? Tiene que ser concreta: «usaremos Laravel con Laravel Nova para el panel de administración», no «una solución moderna».

3. Consecuencias. ¿Qué ganamos y qué perdemos? Toda decisión tiene contrapartidas, y un buen DR es honesto sobre ellas.

4. Fecha y participantes. ¿Cuándo se tomó y quién participó? Así sabes a quién preguntar si surgen dudas.

5. Estado. ¿Está vigente, sustituida o revisada? Las decisiones cambian, y el DR tiene que reflejarlo.

Dónde guardamos los Decision Records

El formato importa, pero la ubicación importa más. Un DR en un documento que nadie abre no sirve de nada.

Los guardamos en 3 sitios, según su naturaleza:

Decisiones de un proyecto concreto: en el propio repositorio, en una carpeta /docs/decisions/. Junto al código y versionadas con él. Es lo primero que ves al entrar en el proyecto.

Decisiones de arquitectura transversales: en la wiki del equipo, organizadas por área (frontend, backend, infraestructura), porque afectan a todos los proyectos.

Decisiones sobre herramientas y procesos: en Notion, junto a los procedimientos internos. Por ejemplo, por qué usamos Figma y no Sketch.

La regla es simple: la documentación tiene que estar donde alguien la buscaría de forma natural en el momento de tener la duda.

Cuándo crear un Decision Record

No documentamos todo, porque sería paralizante. Creamos un DR cuando:

• La decisión es difícil de revertir (framework, base de datos, arquitectura de servicios).
• Esperamos que alguien la cuestione más adelante (incorporaciones al proyecto, crecimiento).
• Hay alternativas razonables que otros podrían proponer, y queremos dejar claro por qué las descartamos.
• La decisión afecta al trabajo de otras personas (procesos, herramientas compartidas).

No creamos DR para decisiones triviales (usar snake_case en las tablas), obvias (usar HTTPS) ni para lo que el propio código ya explica.

Un ejemplo de Decision Record

Este DR está basado en uno de nuestros proyectos, anonimizado y ligeramente simplificado:

DR-014: No usaremos Elasticsearch para la búsqueda de productos

Fecha: septiembre de 2024

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

Contexto: El cliente tiene unos 3.000 productos y quiere búsqueda avanzada (filtros combinados, ordenación por relevancia). Desde backend se propuso implementar Elasticsearch para mejorar el rendimiento y las capacidades de búsqueda.

Decisión: Usaremos la búsqueda nativa de MySQL con índices optimizados. No implementaremos Elasticsearch en esta fase.

Razones:

• Un catálogo de 3.000 productos está holgadamente dentro de lo que MySQL con buenos índices resuelve bien.
• Elasticsearch complicaría el despliegue: requiere un servidor adicional o un servicio gestionado.
• El equipo no tiene experiencia operando Elasticsearch en producción, y el riesgo de problemas de infraestructura supera hoy los beneficios.
• El cliente no tiene presupuesto para la infraestructura adicional.

Consecuencias:

• Buscamos con índices FULLTEXT de MySQL y consultas optimizadas. El rendimiento es aceptable para el volumen actual.
• No tendremos búsqueda tolerante a errores tipográficos ni un cálculo de relevancia avanzado.
• Si el catálogo supera los 10.000 productos o el cliente necesita una búsqueda más sofisticada, habrá que reconsiderarlo.

Estado: Vigente. Revisar si el catálogo supera los 10.000 productos o si el cliente pide funciones de búsqueda que MySQL no puede ofrecer.

Unos meses después, alguien preguntó: «¿por qué no usamos Elasticsearch?». Le pasamos el enlace al DR-014. La conversación duró 3 minutos, no 30. La decisión se mantuvo porque el contexto no había cambiado.

Cómo mantener los Decision Records al día

Un DR obsoleto es peor que no tener ninguno, porque da una falsa seguridad sobre una decisión que ya no aplica.

Nuestra regla: cada vez que alguien cuestiona una decisión documentada, se revisa su DR.

• Si se mantiene, se añade una línea: «revisado el [fecha], contexto sin cambios».
• Si cambia, se marca como sustituido y se crea uno nuevo que explique el contexto actual y enlace al anterior.

Así se va formando un historial que tiene valor por sí mismo: ves cómo evolucionó la arquitectura y por qué. Para incorporar a alguien nuevo al proyecto, es oro. Es la misma lógica que aplicamos a las automatizaciones, donde la falta de documentación convierte cualquier cambio en arqueología, como explicamos en el coste oculto de las automatizaciones mal documentadas.

Objeciones habituales

«No tenemos tiempo para esto.»

Escribir un DR lleva de 10 a 20 minutos. Discutir la misma decisión 3 veces porque no quedó por escrito lleva horas. Son matemáticas.

«El código ya es documentación suficiente.»

El código explica qué se hizo, no por qué. Y el porqué es justo lo que se olvida y lo que más cuesta reconstruir.

«Nadie lee la documentación.»

Si no se lee, el problema es dónde está o cómo está organizada, no la documentación en sí. Un DR en el repositorio aparece de forma natural cuando alguien trabaja en esa parte del código.

«Las decisiones cambian constantemente, acabaríamos con un caos de documentos obsoletos.»

Si algo cambia constantemente, no debería ser un DR. Los DR son para decisiones con consecuencias duraderas. Lo que cambia cada semana es configuración, no arquitectura.

Preguntas frecuentes

¿Debería el cliente ver los Decision Records?

Depende. Los que afectan a decisiones de negocio, sí. Los puramente internos, no. Para clientes con perfil técnico mantenemos una versión resumida.

¿Qué pasa si alguien ignora un DR y hace lo que le parece?

Los DR no son leyes, son el registro de un consenso. Si alguien quiere cambiar una decisión, se discute y se actualiza el DR. Ignorarlo es un problema de cultura de equipo, no de documentación.

¿Necesitamos una herramienta especial?

No. Un archivo Markdown en el repositorio funciona perfectamente. Lo importante es el hábito, no la herramienta. Si quieres empezar hoy, crea la carpeta, escribe el DR de la última decisión que tu equipo haya discutido 2 veces y numéralo como DR-001.

Conclusión

Documentar decisiones técnicas no es una excusa para no tomarlas, ni burocracia para justificar lo que ya hay. Es respeto por el tiempo futuro: el tuyo, cuando no recuerdes por qué hiciste algo; el de tu equipo, cuando alguien entre en un proyecto ya empezado; y el de quien herede el código dentro de unos años.

Si tu equipo pierde tiempo discutiendo decisiones que ya se tomaron, o si entras en proyectos sin entender por qué están hechos así, quizá te falta un sistema de Decision Records. En Baqueiro podemos ayudarte a implantarlo sin complicar tu forma de trabajar. Cuéntanos cómo trabaja hoy tu equipo.