Guidelines to writing a design document
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author: Jan Borsodi
:Revision: $Revision$
:Date: $Date$

Purpose
=======

The main purpose of the design documents is to explain the design decision for
the component to the reader. The reader will usually be one of the following
roles:

Implementor/QA
--------------

The developer can read the design document to understand why it got the design
it did and to get an overview of how the component works. This document should
be able to pinpoint if the implementation deviates from the original design
(ie. bugs).

External developer
------------------

The developer can read the design document to understand how he can use the
component in his application.

Format of the document
======================

To ensure consistency the following format should be employed in the
document. The document should always start with a header which says::

  eZ Component: Component, Design
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Where *Component* is the name of the component. After this header the ReST tags
- :Author:
- :Revision:
- :Date:
should be present, followed by the specific SVN keywords, warpped in $ signs.
In order for SVN to modify those automatically, you need to do:

1. svn propset svn:keywords "Date Revision Author" filename.txt
2. svn commit filename.txt

The rest of the document should contain the following headers. ::

  Design description
  ------------------

Explain the main ideas behind the design, this is usually more details from the
requirements and design goals. The design should list all the classes using
sub headers and give a description of the class and their purpose. ::

  Guidelines
  ----------

If the component has some extra guidelines it can be explained here. This can
for instance be the chosen order of parameters or reasons for deviation of the
general guidelines. ::

  Algorithms
  ----------

The algorithms used in the classes needs to be explained for the
implementor. What generally needs to be explained is how information is passed
around in the system and how data structures are accessed, this can be done
using examples pseudo code or UML diagrams (Usually sequence, collaboration and
activity diagrams). With this description the external developers should be
able to understand the components without looking at the code. ::

  Data structures
  ---------------

If the classes uses some special data structures it should be explained in
detail here. For internal structures the description should be a recommended
structure but the actual structure may change when implementing, external
structures must never change.

Diagrams
========

To clarify the design text it is a good idea to include UML diagrams or other
diagrams which help the reader to understand the component. Required diagrams
are class diagrams, in addition one can use component, object, sequence,
activity, collaboration and state diagrams.


..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79