Clase - Documentacion Tecnica

Documentacion Tecnica 

Por lo general, se entiende por documentar software como solo hacer el Diagrama de Clases en el diseño. Por supuesto que documentar la arquitectura de software no es solo eso, y muchas veces los arquitectos no documentan los proyectos y no acompañan a los desarrolladores en el proceso de documentación. 

Definición teórica de IEEE en su clásica guía de recomendaciones IEEE 1471 (y también se encuentra en el libro "Software Architecture in Practice, 2nd Edition"): "La arquitectura de un sistema de software es la estructura o estructuras del sistema, que incluye elementos de software, las propiedades externamente visibles de esos elementos y la relación entre ellos."

Cuando hablamos de propiedades externamente visibles estamos hablando de las interacciones de un elemento o un sistema con su entorno exterior. Puede ser el flujo de información de entrada y de salida, la forma en que el elemento responde a los estímulos externos y el contrato (la interfaz) de dicho elemento.

Otra definición importante, que encontramos en el libro "Software Systems Architecture: Working with stakeholders using viewpoints and perspectives" es que la arquitectura de software debe ser dirigida por las necesidades de las personas que participan en el proyecto: clientes, usuarios, el departamento de IT, soporte, producción, operación, etc. 

Por otra parte, es el papel del arquitecto explicar los motivos detrás de la elección de determinados elementos arquitectónicos en detrimento de los demás. También la realización de análisis "buy vs. build", es decir, comprar o utilizar un componente de código abierto en lugar de construirlo desde cero. O construir algo desde cero considerando que en el mercado existe ya algo listo para su uso.

Para tener una idea de las diferentes "áreas" las cuales un arquitecto debe hacer frente, podemos volver al libro "Software Systems Architecture". El principio inicial definido por los autores es que "no se puede capturar las necesidades funcionales y las propiedades de calidad de un sistema complejo en un solo modelo comprensible". 

El IEEE establece un poco más. Algunos de estos puntos de vista: Informativo, Concurrencia, Desarrollo, Despliegue, Operativo y Funcional. 

Ya algunas de las perspectivas importantes son: Seguridad, Rendimiento y Escalabilidad, Disponibilidad y Resiliencia, Evolución, Accesibilidad, Internacionalización, Localización, Reglamentación y Usabilidad.

Recomiendo que tenga solamente la información esencial, tal como:

• Elementos y los principales componentes del sistema.
• Capas del sistema.
• Mecanismos arquitecturales necesarios para el sistema.
• Tecnologías elegidas para hacer frente a cada capa y el mecanismo y la motivación detrás de estas opciones.
• Componentes comprados o de código abierto que se utilizarán y la forma en que se tomó la decisión.
• Descripción de los principales patrones de diseño utilizados y por qué la elección.

Además, algunos equipos pueden sentir la necesidad de desarrollar diagramas UML. Estos diagramas relacionados con la arquitectura y el diseño estarán en el modelo de diseño (si usted usa RUP en el proceso de desarrollo). El equipo puede utilizar los diagramas de clase, actividad, secuencia, estados, componentes y despliegue para facilitar la comprensión visual de los elementos y sus relaciones (conforme la definición de arquitectura de software por la IEEE).

Importancia de la Documentación

La documentación adecuada y completa, de una aplicación que se desea implantar, mantener y actualizar en forma satisfactoria, es esencial en cualquier Sistema de Información, sin embargo, frecuentemente es la parte a la cual se dedica l menor tiempo y se le presta menos atención.

Siempre se debe documentar un sistema como si estuviera a punto de irse a Siberia el siguiente mes, para nunca volver. Si la documentación del sistema es incompleta el diseñador continuamente estará involucrado y no podrá moverse a otra asignación.

Referencias:
http://www.dosideas.com/noticias/metodologias/298-como-documentar-la-arquitectura-de-software.html
http://www.monografias.com/trabajos6/dosi/dosi.shtml