:Version: 	1.1

Analysis documentation for basic level official projects.
=========================================================

When providing analysis documentation for a *basic level* official project the following *sections* have to be covered:

* *Introduction*.

  Provide a document entitled "Introduction", containing a brief description of the project and indicating the aims covered and not covered.
  
  This introduction should consist of three or four paragraphs describing briefly the objectives to be covered.

* *Context*.

  Provide a block diagram showing the components of the project in relation to gvSIG and a model of its layers, *user interface/gvSIG application*, *geo/fmap logic*, *library support*.

* *Overview*.

  Present an overview of the major components of the project and the relationships between them. Focus mainly on the components making up the project's API, ignoring components specific to the implementation. Also state the relationship between these components and those of gvSIG.
  
  Normally included are:
  
  * A few paragraphs containing a brief text description of the model and its components.
  
  * A diagram that shows graphically the relationships between the components, clearly distinguishing the project components from those components already existing in gvSIG.
  
  * A brief description of each of the components appearing in the diagram. A paragraph is usually sufficient for each of the artefacts in the model.
  
  * If the diagram is very complex, functionalities should be grouped into more general components, so that complex components in the diagram can be decomposed into others, leading to a greater understanding of the model. In this case, include a list of the components *operating* in the model.

* *Detailed view of components*.

  For each of the components specified in the overview and that *can be used*, include a description and a diagram, similar to that in the *Overview* but for the component in question.

Provide a document for each *section*, presenting as much detail as is required for the project.

It is advisable to follow certain conventions:

- Normally attributes or methods aren't specified for the different components in the diagrams since this documentation is analysis documentation and is not about design. Inclusion of design features at this level would obscure the understanding of the model.

- Diagrams are read from top to bottom and from left to right. With this layout, for example, inheritance can be indicated with super-classes at the top and sub-classes at the bottom, or in the case of one to many relationships, the master entity is shown at the top and the details are shown below or to the right.

- Design diagrams so that they are higher than they are wide (i.e. in portrait layout), and try to have their components at the top and not across the diagram. This is so that if the documentation is printed there will not be much loss in quality if the diagrams are scaled to fit an A4 page.

- Don't scale the diagrams for inclusion in the documentation. If they are too large they will be split into a series of diagrams.

- Try to cross lines as little as possible and don't overlap them with other lines.

- Try to use different entity background colours for grouping sets of functional entities, and provide a legend for identifying the functions.

- Use stereotypes to identify interfaces and abstract classes.

- If an analysis of the implementation's javadocs accompanies the documentation, then a link to the javadoc should be used when referencing one of these entities.

- When inserting diagrams into the documentation, use PNG format with a reduced colour palette (16 or 32 colour palette) in order to reduce the size of the document when accessing it via the web. For more information on this go to `inserting images into documentation`_.

In the event of the project providing functionality that can be used by other projects in the form of a library, it is advisable to submit documentation showing how to use these features.

It is preferable to use the ReST_ format for preparing the documentation, although *basic level* projects submitted in HTML format will also be permitted.

Analysis documentation similar to that required here can be seen at:

* `DAL analysis documentation`_.

It may be helpful to read the `Documentation guide`_ before starting to write the analysis documentation.

Before starting the analysis documentation it is also advisable to contact a member of the *gvSIG architecture group* to discuss what needs to be done.

.. _`Documentation guide` : /plone/projects/gvsig-desktop/docs/devel/guia-para-documentar

.. _`DAL analysis documentation` : /plone/reference_catalog/lookupObject?uuid=b5d8f834cf367e65bea66d61db313982

.. _ReST: http://docutils.sourceforge.net/rst.html

.. _`inserting images into documentation` : /plone/projects/gvsig-desktop/docs/devel/guia-para-documentar/imagenes-en-la-documentación

.. list-table:: change log
   :header-rows: 1

   * - version
     - description

   * - 1.1
     - Added a link on how to insert images into the documentation.

   * - 1.1
     - Added the recommendation to contact the GVSIG architecture group before starting the documentation.