System Design
Documentación viva
Explica cómo mantener documentación útil, versionada, conectada con decisiones y ownership, evitando artefactos obsoletos que nadie consulta ni actualiza.
- Última actualización
- Actualizada
- Nivel
- Profundización
System Design
Explica cómo mantener documentación útil, versionada, conectada con decisiones y ownership, evitando artefactos obsoletos que nadie consulta ni actualiza.
La documentación está viva cuando participa en decisiones, cambios, validaciones y operación. Una página antigua sin estado ni owner no es conocimiento confiable: es una posibilidad sin garantía.
Documentación viva significa mantener una fuente de verdad útil, con alcance, audiencia, owner, vigencia y triggers de actualización. No consiste en copiar el código ni en conservar cada borrador para siempre.
artefacto útil
= pregunta concreta
+ audiencia
+ owner
+ estado
+ fecha
+ relaciones
+ trigger de revisiónDocumenta aquello que reduce ambigüedad, riesgo o coste de coordinación:
No toda función, clase o detalle temporal necesita una página.
Cada concepto debe tener una ubicación principal. Otros documentos pueden resumir y enlazar, pero no duplicar contenido que pueda divergir.
Ejemplo:
Contrato OpenAPI
→ fuente de verdad de endpoints y schemas
Nota de caso de uso
→ explica propósito y enlaza el contrato
Guía frontend
→ explica consumo y enlaza el contratoCopiar manualmente el mismo schema en tres lugares crea contradicciones.
Una taxonomía útil:
Borrador: en exploración, no aprobado.En progreso: está siendo reconstruido o revisado.Listo: cumple el criterio actual.Deprecated: sigue visible para transición, pero no debe usarse en trabajo nuevo.Replaced: fue sustituido y enlaza la fuente vigente.Archived: se conserva por historia, fuera de navegación normal.El estado debe tener significado compartido. Marcar todo como Listo elimina la señal de confianza.
El owner no tiene que escribir cada línea. Su responsabilidad es:
También puede existir owner por dominio, contrato o sistema, no solo por página.
No dependas únicamente de revisiones por calendario. Usa eventos concretos:
Una fecha de revisión ayuda, pero el trigger mantiene causalidad.
Explica por qué existe el sistema, quién lo usa y qué lo rodea.
Casos, procesos, secuencias y estados.
Dominio, datos, contratos, componentes y despliegue.
ADRs, matrices, riesgos y POC.
SLIs, runbooks, recuperación, migraciones e incidentes.
Cada nivel responde preguntas distintas. Mezclarlos produce páginas difíciles de mantener.
Idea principal
Motivación
Modelo mental
Proceso o funcionamiento
Ejemplo explicado
Casos límite
Errores y diagnóstico
Trade-offs
Cómo verificar
Qué debes recordar
Comprueba lo aprendido
ConexionesNo todas las secciones son obligatorias, pero una nota educativa debe superar una definición y una lista.
Las relaciones deben aportar recorrido, no decorar metadata.
Tipos útiles:
En una knowledge base, Topics permiten entrar por tema y Related Notes seguir una ruta conceptual.
Usa identificadores para requisitos, reglas, decisiones, riesgos y pruebas:
OBJ-01
RF-04
RNF-03
RB-07
CU-05
ADR-02
RISK-06
TEST-12El título puede cambiar sin romper la trazabilidad.
Es útil para:
Ventajas: revisión por pull request, historial y automatización.
Es útil para:
No es necesario elegir solo uno. Define qué artefacto gobierna cada concepto.
La automatización puede detectar drift:
Generar documentación no garantiza que explique las decisiones. Combina generación con contexto humano.
Una revisión sostenible responde:
Listo con preguntas abiertas críticas.Un cambio de cancelación de pedidos debería actualizar:
regla de negocio
→ estados
→ caso de uso
→ secuencia
→ API
→ eventos
→ estrategia de pruebas
→ runbook de compensaciones
→ ADR si cambia una decisión importanteLa trazabilidad ayuda a localizar los artefactos; ownership asegura que alguien cierre el ciclo.
El objetivo no es crear más páginas. Prefiere:
Deprecated y Archived?Diseño de un sistema completo aplica todos estos artefactos como una cadena coherente y mantenible.