normas de diseño y construcción

3.1.2.Especificación de estándares, normas de diseño y construcción

Es importante acordar con las personas encargadas del diseño del sistema y con los equipos que procederán a su construcción unas normas que habrá que seguir en la notación de diagramas y documentos. Estas normas pueden venir dadas por estándares o por recomendaciones, o bien ser de uso y creación interna. Obviamente, siempre es recomendable apoyarse en estándares, ya que va a facilitar la comunicación, consistencia, reusabilidad y comprensión por parte de entidades externas o recién incorporadas al equipo.

Deberemos definir:

• Formato y plantilla de los documentos de diseño. • Notación a usar en los diagramas de diseño. • Recomendaciones en cuanto al estilo, idioma y formato de la documentación técnica.

Definición del conjunto de normas y notaciones

Caso práctico

Es conveniente que todos los documentos creados de ahora en adelante, y que van a ser objeto de revisión por parte de equipos diferentes, compartan unas características y mantengan un formato coherente. Para ello, después de estudiar los estándares y recomendaciones sobre el tema, se llega a las siguientes conclusiones:

• Documentos de diseño: estos documentos se deben poder consultar tanto por el personal técnico implicado, como por personal no técnico que pueda revisarlo o consultarlo. Se acuerda que se trabajen en formato OpenDocument y que la versión más reciente esté simultáneamente en PDF para su consulta. Se creará una plantilla que contenga en la primera página: – Título del documento. – Responsable del documento. – Lista de autores que han intervenido y la fecha de su primera intervención.

– Lista resumida de cambios introducidos en el documento a medida que se vayan produciendo (cambio, fecha y autor).

• Diagramas de diseño: para los diagramas de diseño se acuerda usar la notación Unified Modeling

Language, UML (http://www.omg.org/uml/) en su versión 1.5, definida por el Object Management

Group (www.omg.org).

• Documentación técnica: la documentación técnica será posiblemente la que más revisiones sufrirá y contendrá también enlaces a documentaciones de las herramientas usadas, especificaciones de programación (API), etc., por lo que se recomienda usar un formato lo más flexible posible e integrable con las propias herramientas de desarrollo que se usen. Para ello, se decide usar DocBook (www.docbook.org, http://www.oasis-open.org/docbook/), que nos permitirá:

– Partición de un documento en varios ficheros estructurados, susceptibles de ser revisados independientemente. – Fácil inclusión de referencias a otros documentos (enlaces http, figuras, etc.). – Fácil generación de varios formatos para su visualización (PDF, HTML) y con la posibilidad de separar el contenido del documento de su formato.

– Independencia de editor usado, ya que es una implementación de XML y, por lo tanto, modificable en cualquier editor de texto. – Incorporar documentación contenida en el código fuente generado en la fase de desarrollo, de forma automática en muchos casos.

Cabe destacar que al tomar las decisiones se ha dado importancia a la implantación del formato o notación en la industria y a la accesibilidad del mismo, es decir, a la disponibilidad de ejemplos y documentación, así como a un amplio conjunto de herramientas que trabajen con ellos.