Documentación de análisis para proyectos oficiales de nivel básico.
Cuando estemos suministrando la documentación de análisis para un
proyecto oficial de gvSIG de nivel básico tendremos que cubrir los
siguientes apartados:
Introducción.
Deberemos aportar un documento titulado “Introducción” con una
breve descripción del proyecto, indicando qué se persigue
cubrir y qué no.
Esta introducción deberá constar de tres o cuatro párrafos
describiendo de forma concisa los objetivos a cubrir.
Contexto.
Presentará un diagrama de bloques que nos situe los componentes
de nuestro proyecto en relación a gvSIG y el modelo de capas
de esta , interface de usuario/aplicación gvSIG,
lógica geo/fmap, librerías de apoyo.
Visión general.
Presentaremos una visión general de los principales componentes que
forman nuestro proyecto y las relaciones que hay entre ellos.
Nos centraremos principalmente en los componentes que conforman el
API de nuestro proyecto, obviando los componentes específicos de
la implementación. Así mismo indicaremos que relación hay entre
estos y los componentes de gvSIG.
Normalmente tendremos:
- Una breve descripción textual del modelo y sus componentes, unos
cuantos párrafos.
- Un diagrama que nos muestre de forma gráfica las relaciones entre
los componentes, distinguiendo claramente entre los componentes
de nuestro proyecto y los ya existentes en gvSIG.
- Una breve explicación de cada uno de los componentes que aparecen
en el diagrama. Normalmente debería bastar con un párrafo explicativo
por cada uno de los artefactos del modelo.
- Si el diagrama es muy complejo, este agrupará funcionalidades
en componentes más generales, de forma que un componente en este
diagrama podrá descomponerse en otros para una mayor comprensión
del modelo. En este caso se incluirá una lista de los componentes
en los que se explotará nuestro modelo.
Visión detallada por componente.
Para cada uno de los componentes que se haya especificado en la
visión general que puede ser explotado, se incluirá de nuevo
una descripción junto con un diagrama, de forma similar a lo realizado
con la Visión general, pero para el componente en concreto con
el que tratemos.
Se entregará un documento por cada apartado, presentando
tantos apartados de detalle como requiera nuestro proyecto.
Es recomendable seguir algunas convenciones como:
- Normalmente los distintos componentes en los diagramas no contendrán
especificados atributos o métodos, ya que se trata de documentación de
análisis y no de diseño, y incluirlos a este nivel nos llevaría a dificultar
la comprensión del modelo.
- El diagrama se leerá de arriba a bajo y de izquierda a derecha.
Con esto tendremos siempre, por ejemplo, en la herencia las super-clases
en la parte superior y las subclases en la parte inferior, o en las
relaciones unos a muchos, la entidad maestra arriba y la de detalle
abajo o a la derecha.
- Se intentarán componer los diagramas de forma que sean más altos
que anchos, intentando disponer sus componentes a lo alto y no
a lo ancho. Esto es para que si se imprime la documentación estos
no pierdan mucha calidad al ser escalados para adaptarlos a las medidas
de un A4.
- No se escalarán los diagramas para incluirlos en la documentación. Si
estos son demasiado grandes, se descompondrán en otros diagramas.
- Intentaremos que se crucen el mínimo número de líneas posible, así
como no superpondremos unas con otras.
- Intentaremos usar códigos de color de fondo en las entidades para
agrupar conjuntos de funcionales de entidades, suministrando una
leyenda que nos permita identificarlas.
- Usaremos estereotipos para identificar a los interfaces y clases
abstractas.
- Además, si acompañamos a nuestra documentación de análisis de los
javadocs de nuestra implementación, intentaremos que cuando nos
refiramos a una entidad, utilizar un enlace al javadoc de esta.
- Cuando se inserten los diagramas en la documentación, estos
estarán en formato png con una paleta de colores reducida
(paleta de 16 o 32 colores), para evitar que el documento
tenga un peso excesivo para ser consultado por la web.
En el caso de que nuestro proyecto aporte alguna funcionalidad
que pueda ser usada por otros proyectos en forma de librería, se
aconseja presentar documentación de ilustre el uso de esas
funcionalidades.
En cuanto al formato a utilizar para la redacción de la documentación
es preferible el uso de ReST, siendo admitido tambien en proyectos
de nivel básico el uso de HTML.
Podemos ver documentación de análisis similar a la que se requiere
se aporte en:
Es recomendable ponerse en contacto con un miembro del grupo de arquitectura
de gvSIG antes de confeccionar la documentación de análisis para comentar
qué es lo que se va ha hacer.
Registro de cambios
| version |
Descripcion |
|---|
| 1.1 |
Se ha añadido enlace a como insertar imagenes en la documentación. |
| 1.1 |
Se ha añadido la recomendacion de ponerse en contacto con el
grupo de arquitectura de gvSIG antes de confeccionar la documentación. |
