Saltar a contenido

Estándar de documentación técnica — Compulandia

Toda la documentación agregada es consultable en el portal: https://docs.compulandia.com.py

Este repositorio es un template: al crear un repo nuevo (o documentar uno existente) se copia esta estructura y se completan los placeholders {{...}}. Este archivo (docs/index.md) describe el estándar en sí — en el repo destino reemplazalo por una portada breve del sistema (una o dos oraciones y links a arquitectura y runbook alcanzan).

Regla de decisión: ¿dónde va cada documento?

¿El documento cambia cuando cambia el código? - Sí → vive en el repositorio, junto al código, y se versiona con él. - No → va a Outline (documentación organizacional: procesos, RRHH, comercial, políticas generales).

Casos borde: un manual de usuario final no va al repo (no lo mantiene quien programa). Un diagrama de infraestructura sí va al repo de infraestructura.

Estructura obligatoria

repo/
├── README.md          # máx. 40 líneas: qué es, stack, levantar en local
├── AGENTS.md          # comandos, convenciones y restricciones para agentes IA
├── CLAUDE.md          # symlink → AGENTS.md (ln -s AGENTS.md CLAUDE.md)
└── docs/
    ├── arquitectura.md    # componentes, dependencias externas, diagrama
    ├── runbook.md         # deploy, logs, rollback, 3 fallas frecuentes
    └── adr/
        ├── README.md      # índice y reglas
        └── NNNN-titulo.md # una decisión por archivo, formato MADR
  • README de máximo 40 líneas. Si necesita más, ese contenido pertenece a docs/. El README es la puerta de entrada, no la casa.
  • AGENTS.md sin sección "Arquitectura" — genera ruido sin aportar contexto útil; el agente lee docs/arquitectura.md si la necesita.

Directorios opcionales normados (taxonomía)

Un repo crea estos directorios solo cuando tiene contenido de ese tipo — no se inventan otros, y un repo chico sigue teniendo solo la estructura obligatoria:

docs/
├── analisis/          # análisis funcionales/técnicos (fotos en el tiempo)
├── incidentes/        # post-mortems, nombrados AAAA-MM-tema.md
├── estandares/        # convenciones transversales del repo (UI, jobs, logging)
├── integraciones/     # contratos con otros sistemas (un subdir por sistema)
├── rfc/               # propuestas extensas en discusión (NNN-titulo.md)
└── _borradores/       # trabajo en curso — NUNCA se publica al portal
  • La exclusión real de _borradores/ la hace el portal (exclude_docs en docs-portal/mkdocs.yml). El exclude_docs de este template solo alinea la vista local: el portal ignora el exclude_docs de los repos importados (verificado empíricamente, 2026-08-11).
  • Análisis multi-repo: vive en el repo del componente dominante, con cross-links desde los demás; si no hay dominante, en el repo de análisis del sistema.
  • Regla de destilación: al implementarse lo analizado, las decisiones duraderas se destilan en ADRs/arquitectura/runbook del repo y el análisis pasa a estado: implementado. Un RFC decidido genera su ADR corto; el RFC queda como contexto extenso.
  • Los análisis y RFCs son fotos en el tiempo: no se exige mantenerlos actualizados, se marca su estado.

Checklist de publicación por documento

  • Front-matter completo si fue generado con IA.
  • Links internos no salen de docs/; links a código, con URL absoluta de GitHub (los relativos rompen el build estricto del portal).
  • Sin credenciales, tokens, datos reales de clientes ni detalles de infraestructura innecesarios. Criterio: nada que no le dirías a cualquier empleado.
  • estado: refleja la realidad — lo desactualizado se publica como obsoleto con nota de qué lo reemplaza, no como si fuera vigente.

Front-matter obligatorio para documentos generados con IA

Todo documento redactado total o parcialmente por un modelo de IA lleva:

---
generado_por: <modelo, ej: claude-fable-5>
revisado_por: <nombre del humano que validó | pendiente>
fecha: <YYYY-MM-DD>
estado: borrador | validado | implementado | obsoleto
---

implementado aplica a documentos de analisis/ y rfc/: lo decidido ya se construyó y sus conclusiones duraderas fueron destiladas (ver regla de destilación).

Un documento queda en estado: borrador hasta que un humano lo lea y confirme que es cierto. La validación real es el único check que importa: otro dev del equipo debe poder levantar el sistema siguiendo solo el README, sin consultar al autor.

Cómo documentar un repo existente

Todo este proceso está operacionalizado en el prompt de rollout: copiarlo, completar los parámetros y pegarlo en un agente parado en el repo.

  1. Crear repo desde este template (o copiar la estructura a mano).
  2. Triage no bloqueante de la documentación preexistente (en la misma pasada, sin esperar decisión humana): clasificar cada documento existente según la taxonomía y aplicar la regla automática de destino — contenido sensible o datos reales → _borradores/ (no se publica); working files (avances, backlogs, *.progress.md) → _borradores/; todo lo demás → se publica con estado: borrador (si la vigencia es dudosa, con nota "vigencia por confirmar" al inicio). El reporte final lista cada documento con su destino — ninguno excluido en silencio. La revisión humana es posterior, guiada por ese reporte.
  3. Completar README, arquitectura y runbook. Empezar por el runbook: es el que más valor da por hora invertida.
  4. Redactar como máximo 3 ADRs retroactivos — solo decisiones que siguen costando dinero re-discutir (ver docs/adr/README.md).
  5. Verificar que no haya secretos, credenciales ni tokens en el contenido.
  6. Pedir a otro dev que levante el sistema siguiendo solo el README.
  7. Recién ahí, cambiar los front-matter a estado: validado.

Definition of Done — "Repositorio documentado"

□ README.md de máximo 40 líneas: qué es, stack, cómo levantar en local
□ docs/arquitectura.md: componentes, dependencias externas, diagrama
□ docs/runbook.md: deploy, ubicación de logs, rollback, 3 fallas frecuentes
□ docs/adr/ con al menos 1 ADR de una decisión vigente
□ AGENTS.md con comandos, convenciones y restricciones (sin sección "Arquitectura")
□ Verificado: ningún secreto, credencial ni token en el contenido
□ Documentación preexistente con triage en la misma pasada: publicada como
  borrador o movida a _borradores/, y TODA listada en el reporte final —
  ninguna excluida en silencio
□ El repositorio aparece en el portal y su búsqueda devuelve resultados
□ VALIDACIÓN REAL: otro dev levantó el sistema siguiendo solo el README