RFC 005 — Taxonomía de documentación viva: extender el estándar docs-as-code¶

Estado: Aprobada por el equipo con modificaciones mínimas (2026-08-11) Fecha: 2026-08-11 Autores: TI Compulandia + Claude Relacionado con: estándar CompulandiaTI/docs-standard, rollout del portal docs.compulandia.com.py

1. Objetivo¶

Extender el estándar docs-as-code para que toda la documentación técnica que el equipo produce tenga un lugar definido y publicable en el portal — no solo los 4 documentos canónicos (index, arquitectura, runbook, ADRs). Y definir el proceso para que los repos con documentación preexistente la organicen y publiquen durante el rollout, en vez de dejarla local y sin estructura.

2. Problema¶

El rollout del Integrador (2026-08-11) dejó en evidencia el hueco: el repo tenía 21 documentos técnicos reales en docs/ — análisis de sync, post-mortems de incidentes, RFCs, estándares de UI, contratos de integración con PC Manager — y ninguno entró al portal, porque el estándar no define dónde van. Quedaron:

Sin versionar (estaban en .gitignore) y sin front-matter.
Como .md sueltos con nombres inconsistentes (SYNC_ARCHITECTURE.md, failed-sync-manager.md, tn-sync-verification-solution.md).
Con links relativos que salen de docs/ (rompen mkdocs build --strict).
Mezclados con working files (*.progress.md, backlogs) que no deberían publicarse.
Con material interno sin pasada de revisión (rutas de backups, nombres de hosts).

El costo es doble: el conocimiento más valioso del repo (los post-mortems, los contratos de API) es invisible para el resto del equipo, y cada documento nuevo nace sin lugar, perpetuando el desorden.

3. Propuesta: taxonomía extendida¶

Agregar al estándar directorios opcionales pero normados — un repo los crea solo cuando tiene contenido de ese tipo:

docs/
├── index.md, arquitectura.md, runbook.md   # obligatorios (sin cambio)
├── adr/                                    # obligatorio (sin cambio)
├── analisis/          # análisis funcionales/técnicos de features implementadas
├── incidentes/        # post-mortems, nombrados AAAA-MM-tema.md
├── estandares/        # convenciones transversales del repo (UI, jobs, logging)
├── integraciones/     # contratos de API con otros sistemas (un subdir por sistema)
├── rfc/               # propuestas extensas en discusión (numeradas NNN-titulo.md)
└── _borradores/       # trabajo en curso — NUNCA se publica al portal

Reglas que acompañan la taxonomía¶

Working files no se publican. *.progress.md, backlogs, notas de avance van a _borradores/ (excluido del build vía exclude_docs en el mkdocs.yml del template) o directamente a Taiga. El portal muestra conclusiones, no cuadernos de trabajo.
Checklist de publicación por documento (lo que hoy falta y causó la exclusión en masa):
[ ] Front-matter completo (generado_por, revisado_por, fecha, estado).
[ ] Links internos no salen de docs/ (o apuntan a GitHub con URL absoluta).
[ ] Sin credenciales, tokens, rutas de backups ni datos de infraestructura innecesarios (el portal es interno tras Cloudflare Access, pero el criterio es: nada que no le dirías a cualquier empleado).
[ ] estado: refleja la realidad — un análisis desactualizado se publica como obsoleto (con nota de qué lo reemplaza) o se archiva; no se publica como si fuera vigente.
RFC → ADR al decidirse. Los RFCs viven en rfc/ mientras se discuten; cuando una propuesta se decide, se escribe el ADR corto correspondiente que linkea al RFC como contexto extenso. El RFC no se borra.
Todo documento nuevo nace adentro de la estructura, con front-matter desde el día uno. Así se publica solo con el push, sin migraciones posteriores.
El nav se mantiene por sección. Cada directorio nuevo agrega su sección al nav: del mkdocs.yml del repo. mkdocs build --strict en CI avisa de cualquier link roto.

4. Migración de documentación preexistente: proceso de triage¶

Para repos que ya tienen docs (como el Integrador), el rollout incluye un triage con decisión humana:

Inventario y clasificación por tipo (análisis / incidente / estándar / contrato / RFC / working file).
Tabla de triage propuesta por quien ejecuta el rollout: archivo → tipo → destino → vigencia estimada → ¿contenido sensible?.
El humano decide la vigencia. Qué análisis sigue siendo cierto no se deduce del código; lo confirma el equipo. Sin confirmación, el documento se publica como estado: borrador con nota de vigencia dudosa, o queda pendiente.
Ejecución: mover, front-matter, sanitizar, arreglar links, whitelist de .gitignore si aplica, nav, build estricto.

Caso concreto: triage propuesto para el Integrador¶

Documento(s)	Destino	Vigencia estimada
`incidente-colas-atascadas-junio-2026`, `incidente-tests-borran-db-dev-julio-2026`	`incidentes/`	Vigentes (sanitizar rutas de backup)
`ui-design-standards`, `JOB_IMPLEMENTATION_STANDARDS`	`estandares/`	Vigentes
`pc-manager/*` (contratos PCM)	`integraciones/pc-manager/`	Vigentes — otros equipos los necesitan
`rfc/002`, `003`, `004`	`rfc/` (quedan)	004 decidido → genera ADR
`SYNC_ARCHITECTURE`, `failed-sync-manager`, `tn-sync-verification-solution`, `workflow-supplier-product-change`, `product-*-analysis`, `pending-product-confirmation-flow`, `prometheus-monitoring-v1`, `contrato-sync-productos-compuestos-pcm`	`analisis/` o `integraciones/`	A confirmar por el equipo (varios son pre-fix de junio 2026)
`*.progress.md`, `SYNC_IMPROVEMENTS_BACKLOG`	`_borradores/` o Taiga	No se publican
`MIGRATION_GITLAB_TO_GITHUB`, `PLAN_MEDUSA_VARIANT_IMAGES`, `CATEGORY_MIGRATION_RFC`	Archivar o publicar como `obsoleto`	Históricos / ejecutados

5. Cambios concretos que implica esta propuesta¶

En CompulandiaTI/docs-standard (un PR):

Documentar la taxonomía y sus reglas en docs/index.md del template.
Agregar _borradores/ al exclude_docs del mkdocs.yml del template.
Sumar el checklist de publicación como sección del estándar.
Agregar al Definition of Done: "□ La documentación preexistente pasó por triage: publicada, en _borradores/, o listada como pendiente — ninguna excluida en silencio".

En cada repo con docs preexistentes (el Integrador primero, como piloto):

Ejecutar el triage de §4 y la migración.
Ampliar la whitelist del .gitignore a los nuevos directorios.

En el prompt de rollout (§6): agregar el paso que evita que esto vuelva a pasar.

6. Sección propuesta para el prompt de rollout de repos¶

Agregar entre el PASO 2 y el PASO 3 del prompt actual:

PASO 2b — Documentación preexistente (no dejarla atrás)
Si el repo ya contiene documentación previa al estándar (en docs/ o en
cualquier otro directorio: *.md sueltos, carpetas de análisis, RFCs,
post-mortems, contratos):

1. Inventariá TODOS los documentos y clasificalos por tipo: análisis /
   incidente-postmortem / estándar / contrato de integración / RFC /
   working file (avances, backlogs, *.progress.md).
2. Armá una TABLA DE TRIAGE: archivo → tipo → destino propuesto
   (analisis/, incidentes/, estandares/, integraciones/, rfc/,
   _borradores/) → vigencia estimada (vigente / dudosa / obsoleto) →
   ¿contenido sensible? (sí/no).
3. La vigencia la decide el humano, no vos. Si el desarrollador está
   disponible, presentale la tabla antes de mover nada. Si no lo está:
   migrá solo los documentos claramente seguros (incidentes, estándares,
   contratos sin datos sensibles) publicándolos como estado: borrador,
   y dejá el resto intacto y listado en el reporte final como
   "pendiente de triage" — nunca excluido en silencio.
4. Al migrar cada documento: mover al directorio que corresponda con
   nombre kebab-case (incidentes: AAAA-MM-tema.md), agregar front-matter
   (estado según triage; lo obsoleto se publica marcado obsoleto o se
   archiva), arreglar links que salgan de docs/, y sanitizar datos
   sensibles (rutas de backups, hosts, credenciales aunque parezcan de
   ejemplo).
5. Working files van a docs/_borradores/ (excluido del portal vía
   exclude_docs) — nunca al nav.
6. Actualizá whitelist de .gitignore (si aplica), nav de mkdocs.yml, y
   volvé a correr mkdocs build --strict.
7. El reporte final incluye la tabla de triage completa con el destino
   final de CADA documento encontrado.

7. Costos y riesgos¶

Esfuerzo de migración: ~2-4 h por repo con documentación acumulada (triage humano incluido); repos nuevos, costo cero — nacen ordenados.
Riesgo de publicar algo desactualizado: mitigado por el triage humano y el estado: obligatorio; un doc marcado borrador/obsoleto avisa al lector.
Riesgo de publicar algo sensible: mitigado por el checklist §3.2 y porque el portal ya está tras Cloudflare Access (audiencia interna).
Más directorios ≠ más burocracia: son opcionales; un repo chico sigue teniendo solo los 4 canónicos.

8. Próximos pasos¶

Discutir esta propuesta con el equipo (esta reunión / hilo).
Si se aprueba: PR a docs-standard con taxonomía + checklist + prompt 2b.
Piloto: ejecutar el triage del Integrador (§4.1) con la tabla ya propuesta — el equipo solo marca vigente/obsoleto por fila.
Replicar en los siguientes repos del rollout ya con el prompt extendido.