El enfoque de alto nivel que generalmente adopto al documentar arquitecturas (o incluso diseños más detallados, de nivel inferior) es:
- Identificar las partes interesadas en el diseño. El equipo de ingeniería / desarrollo es una de las partes interesadas. Su equipo de pruebas / garantía de calidad, el equipo de infraestructura de TI, la gestión del proyecto, y tal vez el personal de apoyo también pueden ser partes interesadas del sistema y están interesados en diversos aspectos del diseño.
- Identificar las áreas de preocupación en su sistema. Si su sistema tiene una base de datos, un punto de vista es la estructura de la base de datos. Si tiene un sistema distribuido, entonces los administradores del sistema o el personal de atención al cliente pueden estar interesados en el lugar donde se instalan los componentes. Si tiene una interfaz pública, entonces los desarrolladores externos están interesados en lo que es esa interfaz: formatos de archivo, formatos de datos, etc. Si tiene muchos algoritmos complejos, entonces los diseñadores/mantenedores de algoritmos están interesados en los flujos de trabajo y los pasos del algoritmo. Cada punto de vista que identifique es un conjunto específico de preocupaciones.
- Para cada punto de vista que tenga, elija una representación apropiada. Para su punto de vista de la base de datos, tal vez los diagramas de entidad-relación y un diccionario de datos pueden ser útiles. Para las interfaces públicas, se pueden incluir documentos de esquema XML o documentación de la API como parte de su documentación. Para los algoritmos complejos, considere los diagramas de actividad o de resumen de interacción de UML. Cuando elija una notación, prefiero las notaciones bien conocidas y definidas para no tener que explicar mi notación a otra persona y poder simplemente indicarle el material de referencia existente si no conoce los símbolos utilizados.
- Añada descripciones textuales y racionales alrededor de los diagramas. Explique no sólo cuáles fueron las decisiones arquitectónicas que tomó, sino qué le llevó a tomar esas decisiones.
Los marcos arquitectónicos, como el Marco de Zachman, el Marco Arquitectónico del Grupo Abierto, el Marco Arquitectónico del Departamento de Defensa y otros marcos arquitectónicos ayudan a definir puntos de vista esenciales y puntos de vista que son generalmente aplicables.
En última instancia, "la mejor" documentación es la que satisface las necesidades de las partes interesadas. Identificar quién necesita la información y qué necesita exactamente es el primer paso.