ADR-0001 · Documentación técnica en repositorios (docs-as-code), no en Outline

• Estado: aceptado
• Decisores: equipo DevOps Compulandia
• Fecha de la decisión: 2026-08-10

Contexto y problema

La documentación técnica estaba dispersa: notas locales por desarrollador, conocimiento operativo de aplicaciones internas no transferible, y decisiones técnicas sin registro que se re-discutían o revertían sin conocer el contexto original. Existía Outline como wiki organizacional, pero la documentación técnica ahí se desactualiza: nadie la ve al modificar el código y no participa del flujo de revisión de PRs.

Opciones consideradas

1. Docs-as-code: la documentación técnica vive en cada repo y se versiona con el código
2. Centralizar toda la documentación técnica en Outline
3. Wiki técnica separada (Confluence, Wiki.js u otra herramienta nueva)

Decisión

Docs-as-code. La documentación que cambia cuando cambia el código debe vivir junto al código: se revisa en el mismo PR, se versiona con git, y su desactualización es visible en el diff. Outline queda reservado para documentación organizacional (la que no cambia con el código). Un portal unificado (MkDocs) agrega los repos para búsqueda centralizada, sin duplicar la fuente de verdad.

Consecuencias

Positivas

• La documentación participa del flujo de revisión y se versiona con el código.
• Los agentes de IA que trabajan sobre el repo acceden al contexto sin pasos extra.
• Fuente de verdad única por sistema; el portal solo agrega, no duplica.

Negativas / deuda asumida

• Se necesita un portal (repo + CI + hosting) para la búsqueda transversal: infraestructura nueva que mantener.
• Convivencia de dos herramientas (repos + Outline) exige una regla de decisión clara y disciplina para respetarla.
• La documentación existente en Outline que sea técnica migra solo bajo demanda; habrá un período con material desactualizado ahí.