vlaskos/architecture-documentation-skill

Documentar arquitecturas de software

La documentación de arquitectura existe para responder preguntas que los interesados te harán en reuniones durante toda la vida del sistema: ¿Cómo está organizado esto? ¿Por qué es así? ¿Dónde modifico X? ¿Funcionará bajo Y? Una buena documentación responde esas preguntas una vez, por escrito, en una forma que cada lector pueda usar realmente.

Esta habilidad es un método para producir esa documentación y para revisar documentación escrita por otra persona. Está construida sobre estándares y modelos abiertos y gratuitos, no sobre un único texto con derechos de autor:

• ISO/IEC/IEEE 42010 — el estándar internacional para la descripción de arquitectura. Proporciona el vocabulario utilizado en toda la habilidad: interesado, preocupación, punto de vista, vista, modelo, decisión de arquitectura, fundamento.
• El modelo C4 (Simon Brown) — un conjunto ligero de diagramas estructurales en cuatro niveles de zoom: contexto, contenedor, componente, código.
• El modelo de vistas 4+1 (Philippe Kruchten) — cinco perspectivas concurrentes: lógica, proceso, desarrollo, física y los escenarios que las unen.
• arc42 — una plantilla de documentación con licencia Creative Commons cuya estructura de secciones es un esqueleto práctico para una descripción completa de arquitectura.
• Registros de Decisiones de Arquitectura (el formato ADR popularizado por Michael Nygard) — un archivo corto por cada decisión significativa.

El método

La documentación se guía por quién la lee y qué necesita decidir o hacer. Trabaja en este orden.

1. Identifica a los interesados y sus preocupaciones. Enumera quiénes dependen de la arquitectura (desarrolladores, operadores, revisores de seguridad, propietarios de producto, integradores, auditores) y qué necesita cada uno que la documentación responda. Una preocupación es una pregunta o cualidad que importa a alguien: "¿puedo implementar esto sin tiempo de inactividad?", "¿dónde viven los datos del cliente?", "¿cómo añado un nuevo proveedor de pagos?". Las preocupaciones determinan todo lo demás. Consulta references/viewpoints-and-views.md.

2. Selecciona puntos de vista que cubran las preocupaciones. Un punto de vista es un tipo reutilizable de vista: las convenciones para construir un tipo de representación (qué elementos muestra, qué relaciones, qué notación). Elige el conjunto más pequeño de puntos de vista que, juntos, aborden todas las preocupaciones importantes. No escribas una vista que nadie necesita. Consulta references/view-catalog.md.

3. Construye las vistas. Cada vista es una representación del sistema desde un punto de vista: un diagrama más la prosa que lo explica. La mayoría de los sistemas necesitan una vista estructural (cuáles son las piezas y cómo dependen entre sí), una vista de tiempo de ejecución (qué sucede en tiempo de ejecución: procesos, flujos, interacciones) y una vista de despliegue (cómo el software se asigna a la infraestructura). Añade vistas de comportamiento para las partes donde la sincronización o la secuencia son el punto central. Los niveles C4 y las perspectivas 4+1 son formas concretas y probadas de poblar estas vistas. Consulta references/view-catalog.md.

4. Captura las decisiones y su fundamento. La parte más valiosa y más frecuentemente omitida de la documentación de arquitectura es el por qué. Registra cada decisión significativa (el contexto, las opciones consideradas, la elección y las consecuencias) como un Registro de Decisión de Arquitectura. El fundamento es lo que permite que la siguiente persona modifique el sistema de forma segura en lugar de adivinar. Consulta references/decisions-and-rationale.md.

5. Ensambla la descripción y añade orientación. Un montón de vistas no es un documento. Añade el tejido conectivo: una visión general del sistema de una página, una declaración de alcance y contexto, un glosario y una nota explícita sobre cómo se relacionan las vistas entre sí (el mismo elemento visto en dos vistas es la principal fuente de confusión para el lector, así que resuélvelo). Usa references/documentation-template.md para un esqueleto completo de secciones.

6. Revisa antes de publicarlo. Evalúa la documentación contra references/review-checklist.md. Los dos modos de fallo son incompletitud (una preocupación que ninguna vista aborda) y ilegibilidad (diagramas sin claves, términos no definidos, ninguna declaración de lo que el lector está viendo).

Cómo usar esta habilidad

• Empezar desde cero → sigue los seis pasos anteriores, usando references/documentation-template.md como estructura objetivo.
• Decidir qué escribir → references/viewpoints-and-views.md (preocupaciones → puntos de vista) y references/view-catalog.md (el catálogo de tipos de vista).
• Registrar una decisión → references/decisions-and-rationale.md (formato ADR y ejemplos).
• Revisar documentación existente → references/review-checklist.md.
• Elegir entre marcos de trabajo o mapear uno sobre otro → references/frameworks-map.md.

Principios

• Escribe para un lector, no para la exhaustividad. Cada vista, diagrama y párrafo debe poder rastrearse hasta una preocupación de un interesado. Si no puedes nombrar quién lo necesita, elimínalo.
• Todo diagrama necesita una clave. La notación que "parece obvia" no lo es. Indica qué significan las cajas y las líneas. Un diagrama sin explicación es una suposición esperando a salir mal.
• Registra el fundamento a medida que avanzas. Las decisiones son baratas de capturar en el momento en que las tomas y costosas de reconstruir después.
• Mantenlo cerca del código y actualizado. La documentación que se aleja de la realidad es peor que ninguna, porque la gente confía en ella. Prefiere un documento más pequeño que mantendrás sobre uno grande que no mantendrás.
• Deja que el riesgo del sistema determine la profundidad. Documenta en detalle las partes donde equivocarse es costoso; esboza el resto.