Por qué la documentación de arquitectura importa para equipos modernos
Déjame contarte sobre el peor trimestre de mi carrera como ingeniero.
Era 2019. Era el tech lead del equipo de plataforma core de una startup fintech. Teníamos una hermosa arquitectura de microservicios — 23 servicios, event-driven, propiamente aislados. El sistema funcionaba sin problemas. Sabíamos exactamente cómo funcionaba todo.
Luego tres cosas pasaron en rápida sucesión:
- Sarah, nuestra ingeniera principal, se fue a una empresa FAANG
- Marcus, quien construyó nuestra integración de pagos, fue reclutado por un competidor
- Lisa, la única persona que entendía nuestro servicio legacy de reconciliación, salió por licencia médica extendida
En seis meses, la mitad del conocimiento institucional sobre nuestra arquitectura salió por la puerta. Y casi no teníamos documentación.
Lo que siguió fueron meses de ingeniería inversa de nuestros propios sistemas. Funcionalidades que deberían haber tomado una semana tomaban un mes porque teníamos que descubrir primero cómo funcionaba el código existente. Introdujimos bugs porque no entendíamos las razones sutiles detrás de ciertas decisiones de diseño. Hicimos cambios arquitecturales que entraban en conflicto con restricciones que habíamos olvidado que existían.
Esa experiencia me convirtió de escéptico de la documentación a evangelista de la documentación. No porque de repente me encantara escribir docs, sino porque vi de primera mano lo que pasa sin ellas.
El costo real de la documentación faltante
Seamos honestos sobre lo que cuesta la mala documentación. No en términos vagos de "es importante", sino en impacto concreto que he presenciado.
Tiempo de onboarding
En esa fintech, los nuevos ingenieros tomaban 4-6 meses para volverse productivos. No porque no fueran inteligentes — eran excelentes — sino porque entender nuestro sistema requería absorber años de conocimiento tribal por ósmosis.
Después de invertir en documentación, eso bajó a 6-8 semanas. Mismo calibre de ingenieros, misma complejidad del sistema. La única diferencia era que tenían un mapa en lugar de vagar a ciegas.
Las matemáticas son simples. Si contratas 5 ingenieros al año y cada uno desperdicia 3 meses poniéndose al día, son 15 meses-persona perdidos anualmente. A salarios de ingeniero senior, estás viendo un cuarto de millón de dólares en productividad perdida — cada año.
Latencia de decisiones
Sin documentación, cada discusión arquitectural empieza desde cero.
"¿Por qué usamos Kafka aquí en lugar de RabbitMQ?"
Nadie sabe. Discutamos por dos horas.
"¿Podemos agregar una llamada sincrónica del Servicio A al Servicio B?"
Depende de alguna restricción que podría existir. Pasemos un día investigando.
"¿Qué pasa si el servicio de pagos se cae?"
Buena pregunta. Tracemos a través del código por una semana.
Cuando el contexto arquitectural está documentado, estas preguntas tienen respuestas. No siempre respuestas inmediatas, pero al menos sabes dónde buscar. Los ciclos de decisión se reducen de semanas a días.
Respuesta a incidentes
2 AM. El pager suena. El flujo de checkout está fallando. Eres el ingeniero de guardia, y solo has estado en la empresa dos meses.
Sin documentación, estás haciendo grep frenéticamente a través del código, tratando de entender el sistema mientras está en llamas. Estás haciendo ping en canales de Slack esperando que alguien que conoce el flujo de pagos esté despierto.
Con documentación, abres la arquitectura del sistema, ves cómo funciona el flujo de checkout, identificas qué servicios están involucrados, y sabes dónde buscar el problema. Incluso podrías encontrar un runbook de troubleshooting para exactamente este escenario.
He estado en ambos lados de esto. La diferencia en tiempo promedio de recuperación es dramática.
Acumulación de deuda técnica
Aquí hay un patrón que he visto repetidamente:
- Un equipo construye un sistema bien arquitecturado
- La documentación no existe o se vuelve obsoleta
- Nuevos ingenieros se unen, no entienden la arquitectura
- Agregan funcionalidades que violan principios arquitecturales
- La deuda técnica se acumula
- Eventualmente, alguien propone una reescritura
La reescritura no siempre es necesaria. Frecuentemente, la arquitectura original estaba bien — solo no era entendida. Sin documentación, cada principio arquitectural está a una rotación de equipo de ser olvidado.
Cómo se ve realmente la buena documentación
Documentar por documentar es inútil. He visto equipos producir cientos de páginas de docs que nadie lee. La clave es documentar las cosas correctas de la manera correcta.
Documenta el porqué, no solo el qué
El código muestra lo que hace el sistema. La documentación debería explicar por qué.
¿Por qué elegimos PostgreSQL en lugar de MongoDB? ¿Por qué estos servicios están separados en lugar de combinados? ¿Por qué este endpoint acepta este formato particular?
Estas preguntas de "por qué" tienen respuestas que no están en el código. Están en las cabezas de las personas que tomaron las decisiones. Si no las escribes, se pierden cuando esas personas se van.
Hazla descubrible
La mejor documentación es inútil si nadie puede encontrarla. Nuestra fintech de hecho tenía algo de documentación — enterrada en un espacio de Confluence que no estaba enlazado desde ningún lado, con una función de búsqueda que apenas funcionaba.
La documentación debería ser:
- Enlazada desde el código (archivos README, comentarios de código con enlaces a docs)
- Organizada lógicamente (no solo volcada cronológicamente)
- Buscable (búsqueda full-text a través de todos los docs)
Eventualmente movimos nuestra documentación de arquitectura al repositorio mismo. Ahora aparece en revisiones de código, se versiona con el código, y no puede alejarse demasiado de la realidad.
Hazla mantenible
La documentación que es dolorosa de actualizar no se actualiza.
Por esto soy escéptico de los diagramas UML elaborados. Son hermosos cuando se crean y desesperanzadamente obsoletos seis meses después porque actualizarlos requiere herramientas y habilidades especializadas.
Los formatos simples funcionan mejor:
- Markdown que cualquiera puede editar
- Diagramas basados en texto (Mermaid, PlantUML) que viven junto al código
- Diagramas C4 que son intencionalmente simples de mantener
La documentación que se mantiene es la documentación que es fácil de mantener.
Apunta a múltiples audiencias
Diferentes personas necesitan diferentes niveles de detalle.
Un nuevo ingeniero necesita una vista general del sistema. Un product manager necesita entender los límites de servicios. Un arquitecto necesita ver las relaciones de componentes. Un ingeniero de guardia necesita información operacional.
El modelo C4 funciona bien aquí porque explícitamente provee diferentes niveles de zoom. Contexto de sistema para ejecutivos, diagramas de containers para arquitectos, diagramas de componentes para desarrolladores.
Pasos prácticos para empezar a documentar
Si empiezas desde cero, aquí está el enfoque que he encontrado que funciona:
Semana 1: Contexto de Sistema
Pasa algunas horas creando un diagrama que muestre:
- Tu sistema como una sola caja
- Quién lo usa
- A qué sistemas externos se conecta
Solo esto tiene valor. Establece límites y da a los nuevos miembros del equipo un punto de partida.
Semana 2: Diagrama de Containers
Descompón tu sistema en sus piezas desplegables:
- Servicios, aplicaciones, bases de datos
- Cómo se comunican
- Qué tecnologías usan
Esto se vuelve la referencia para discusiones de infraestructura y onboarding.
Semana 3: Decisiones clave
Documenta tus tres decisiones arquitecturales más importantes:
- Qué se decidió
- Por qué se decidió
- Qué alternativas se consideraron
Esto previene re-litigar viejos debates y ayuda a los nuevos miembros del equipo a entender la razón detrás de la forma del sistema.
Hacia adelante: Parte del workflow
La documentación inicial es la parte fácil. Mantenerla actualizada es más difícil.
Haz que la documentación sea parte de tu definición de done. Si un PR cambia la arquitectura, debería actualizar los docs relevantes. Esto no pasa automáticamente — requiere disciplina de revisión y compromiso cultural.
Algunos equipos agregan checks automatizados: un job de CI que verifica que los archivos README existen, o un template de PR que pregunta "¿Este cambio modifica la arquitectura? Si es así, ¿actualizaste los docs?"
El desafío cultural
Seré honesto: hacer que un equipo documente es frecuentemente una batalla cultural.
Los ingenieros generalmente prefieren escribir código que escribir docs. La documentación se siente como overhead, no como output. Cuando las fechas límite se acercan, los docs son lo primero que se recorta.
Lo que he encontrado que ayuda:
Hazlo personal
Cuando un nuevo ingeniero se une, pídele que documente lo que aprende mientras hace onboarding. Está viendo el sistema con ojos frescos y notando gaps que los veteranos se pierden. Además, se beneficia directamente de tener documentación que desearía que existiera.
Celebra la documentación
Menciona las actualizaciones de documentación en sprint reviews. Reconoce a los ingenieros que mantienen buenos docs. Haz visible que la documentación es valorada, no solo tolerada.
Automatiza lo que puedas
Mientras menos documentación manual se requiera, más probable es que suceda. Usa herramientas que generan docs desde código. Usa IA para crear primeros borradores. Usa diagramas-como-código que se actualizan automáticamente.
Esto es en parte por qué construí Archyl. El overhead manual de crear y mantener documentación de arquitectura es una barrera mayor. El descubrimiento asistido por IA y la edición visual reducen esa barrera.
Conéctalo al dolor
Las personas cambian comportamiento cuando sienten dolor. La próxima vez que alguien pase días entendiendo un sistema porque no hay documentación, señálalo. "Esto podría haber sido una tarea de una hora si tuviéramos docs."
Conclusión
La documentación no es emocionante. No es la razón por la que ninguno de nosotros entró a la ingeniería de software. Pero es la diferencia entre un sistema que sobrevive a sus creadores y uno que se vuelve un desastre no mantenible.
¿La fintech que mencioné antes? Después de ese período doloroso, invertimos seriamente en documentación. Diagramas de arquitectura, decision records, runbooks, todo. Tomó unos seis meses de esfuerzo dedicado.
La siguiente vez que alguien se fue, apenas interrumpió al equipo. Su conocimiento estaba en el sistema, no solo en su cabeza.
Eso es lo que la documentación realmente es: un seguro contra la pérdida de conocimiento. Y como todo seguro, se siente caro hasta que lo necesitas.
Continúa tu viaje de documentación: Introducción al modelo C4 | Architecture Decision Records | Documentando flujos de usuario