Software Architect · Módulo 18
La documentación arquitectónica no es para el archivo. Existe para que la gente nueva pueda entender el sistema, y la gente vieja pueda recordar por qué se tomaron las decisiones.
ADR · C4 · runbook · decision record · context
Documentás algo más que el resultado — documentás el contexto: por qué esta opción, qué alternativas se descartaron y cuándo revisitar la decisión.
Un ADR fija una decisión en el tiempo
La foto de la obra en construcción no reemplaza al plano, pero ayuda a entender por qué la pared quedó acá.
Un Architecture Decision Record suele tener context, decision, consequences, alternatives y status. No tiene que ser largo. Su trabajo es preservar el reasoning.
Un año después, el equipo puede no acordarse de por qué eligió Postgres, por qué descartó Kafka o por qué mantuvo una sync API. El ADR evita repetir la misma discusión sin el contexto original.
Un diagrama tiene que responder una pregunta
El mapa del subte no muestra las cloacas — al pasajero no le hacen falta. Un buen diagrama también elige su nivel de detalle.
El C4 model es útil como un set de niveles: context, container, component, code. Un stakeholder necesita el context. El equipo necesita containers y los components importantes. El incident response necesita la runtime view y las dependencias.
Un único diagrama gigante de "todo el sistema" suele ser inútil: o queda obsoleto o se vuelve ilegible.
La buena documentación vive al lado de los cambios y tiene un owner.
Ejemplo: un ADR para la elección de cola
En la minuta de una reunión, lo importante no es sólo la decisión — también es por qué las otras opciones no encajaban.
El ADR registra: necesitamos entregar domain events con replay, ordering by key y storage durable. Evaluamos RabbitMQ, managed Kafka y un database outbox. Elegimos managed Kafka por el throughput — y aceptamos el costo operacional y la carga de schema governance.
Un documento así le permite a un equipo futuro ver cuándo la decisión sigue siendo válida y cuándo el contexto cambió.
Antiejemplo: Confluence como cementerio
Un depósito lleno de instructivos viejos impresiona — hasta que nadie sabe cuál sigue siendo el vigente.
La documentación vive aparte del código, no tiene owner, no se actualiza en los PRs y está llena de screenshots de hace tres años. La gente nueva aprende rápido a ignorarla.
Menos documentos con un lifecycle claro funcionan mejor: owner, fecha de last reviewed, link desde el código, update obligatorio ante cambios arquitectónicos.
- ¿Qué decisiones merecen un ADR? - ¿Qué diagrama necesita alguien nuevo en su primer día? - ¿Qué runbooks necesita el on-call? - ¿Cómo se entera el equipo de que un documento quedó obsoleto?