La documentación de arquitectura va mucho más allá de los diagramas. Necesitas una forma de gestionar el conocimiento que se genera durante la ejecución de un proyecto, y los generadores de sitios estáticos como Quarto te permiten centralizar diseños, decisiones y métricas en un solo lugar navegable.
En el proyecto del Banco Interamericano de Desarrollo, este enfoque agrupa no solo documentos de diseño o architectural decision records, sino también otros artefactos que conservan valor en el tiempo.
¿Qué es un generador de sitios estáticos y por qué usarlo?
Un generador de sitios estáticos transforma código fuente sencillo en un sitio web completamente funcional. Con muy poco esfuerzo obtienes documentación navegable, versionable y fácil de mantener.
¿Qué es un generador de sitios estáticos? Es una herramienta que toma archivos en formatos simples como markdown y los convierte en páginas HTML listas para publicar, sin necesidad de un servidor dinámico.
En nuestro caso usamos Quarto, una alternativa open source que destaca porque no se limita a páginas web. También produce:
- Dashboards interactivos con información cuantitativa del proyecto.
- Presentaciones útiles para equipos no técnicos.
- Recetas de automatización reutilizables por el equipo.
¿Cómo se integra Quarto en un monorepositorio?
Dentro del monorepositorio agregamos un proyecto nuevo, pero este no se basa en un lenguaje de programación tradicional, sino en las herramientas de shell del generador. El código fuente está escrito en notación markdown, lo que permite redactar descripciones como texto normal que luego se renderiza como HTML.
Lo interesante viene con los notebooks: puedes incluir notebooks con código fuente en Python que también se renderizan como HTML. Aquí ocurre una integración poderosa entre arquitectura de software, arquitectura de datos e ingeniería de datos.
¿Por qué importa? Porque todo proyecto genera metadata valiosa para analizar:
- Velocidad de entrega.
- Calidad de los productos.
- Personas que participan más activamente en los proyectos.
¿Cómo publicar documentación viva con Quarto?
Con un par de comandos, Quarto ejecuta toda la documentación y la convierte en un sitio HTML navegable. En el ejemplo del proyecto incluimos todos los architectural decision records, tanto del monorepo como de los polirepos, junto con un dashboard interactivo.
¿Qué es un dashboard de documentación viva? Es un panel navegable que muestra resultados de análisis actualizados, como avances del proyecto, cambios en pruebas o exploraciones de datos, dentro de la propia documentación.
Esto te da documentación en vivo. Las personas no leen un archivo estático: ven resultados actuales del análisis, cómo cambian las pruebas y los escenarios de un caso de uso, e incluso exploraciones de conjuntos de datos para validar si las estimaciones, condiciones de frontera o restricciones siguen siendo correctas.
¿Por qué la gestión del conocimiento es una inversión a futuro?
Ser explícito en las formas y en la calidad de los documentos que generas promueve la discusión asíncrona. No dependes de tantas reuniones, reduces el tiempo para tomar decisiones y aceleras los acuerdos del equipo.
También facilita la memoria del proyecto y permite enfatizar los puntos donde realmente quieres llamar la atención. Cuando alguien nuevo llega al equipo, encuentra contexto sin tener que reconstruirlo desde cero.
¿Qué alternativas existen para documentar tu arquitectura?
No todo proyecto necesita un generador de sitios estáticos. Tienes varios caminos según el contexto de tu organización:
- Herramientas de ofimática como Office o Google Docs.
- Wikis especializadas como Confluence.
- Sistemas de gestión documental embebidos en toda la compañía, que tratan la documentación del proyecto como parte del conocimiento global de la organización.
La elección depende de qué tan asíncrono trabaja tu equipo, qué tan técnica es la audiencia y si necesitas integrar análisis de datos vivos dentro de tus documentos.
Cuéntame en los comentarios cómo gestionas tú la documentación, qué herramientas usas y cómo validas los documentos que generas en tu arquitectura.
