# 18. Documentación Cómo escribir ADRs, diagramas, runbooks y system context para que la documentación ayude a tomar decisiones — y no quede obsoleta en una semana. - **Author:** Fedor Chishchin - **Level:** advanced - **Reading time:** ~25 minutos de lectura - **Published:** 2026-05-23 - **Source:** https://fedorthinks.com/es/learn/software-architect-18-documentation --- ## 1. La idea central 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. ## 2. Ejemplo y antiejemplo 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. #### Autoevaluación - ¿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? Próximo módulo: [Comunicación](./software-architect-19-communication).