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

Purpose
=======

The main purpose of the requirements documents is to explain what the component
should do or which problem it should solve. The reader will usually be one of
the following roles:

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

The developer can read the requirements document to understand the original
reasoning behind the component. This document should be able to pinpoint if the
design or implementation deviates from the original idea (ie. bugs).

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

The developer can read the requirements document to understand the concepts of
the component. He will be able to understand what the component will do and
what it will not do. If the developers sees missing points in the requirements
he can contact the author and work together for a better solution (if
possible).

End user
--------

The user can read the requirements document to understand what she can use it
for and what problems it solves for her. It will also make it clearer for her
if the problem she is having with the component is actually a bug or just
something it was never indented to solve.

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, Requirements
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Where *Component* is the name of the component. After this header the
*:Author:*, *:Revision:* and *:Date:* tags should be present. In order for SVN
to modify those automatically, you need to do:

1. svn propedit svn:keywords filename.txt
2. Enter Author, Revision and Date in that file, separated by newlines.
3. svn commit

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

  Introduction
  ============

  Description
  -----------

A short description of the component should be placed here. It is usually taken
from the component description page. ::

  Current implementation
  ----------------------

If there exists a current implementation of the component it should be
mentioned here. It should describe what the current implementation does and
pinpoint the special features and problems of it. ::

  Requirements
  ============

This must explain the requirements of the package as seen from the end user or
external developers point of view. The requirements must not be technical or
mention design and implementation details (unless it really relates to it). Using
a bullet list for the requirements can be a good idea.
It is important that everything that the component should solved is mentioned
here, it should not be up to the designer or implementer to add extra features.
::

  Design goals
  ============

Based on the requirements some design goals should be explained. These goals
are more technical and detailed without resorting to specifying the design
itself. This is usually not of interest to the end user but might be useful for
the external developers, class designers and implementors. ::

  Special considerations
  ======================

This section can be used to explain special considerations that must be
followed when designing or implementing the component. Usually this is
functionality the component should not support. ::

  Format
  ======

If the component deals with file formats, transfer formats etc. it should
describe them here. Basically this is a more detailed requirement for what the
component should support. If the format is already defined it should only link
to the web page or file which describes it.

Diagrams
========

To clarify the requirements text it might be a good idea to include UML
diagrams or other diagrams which help the reader to understand the component.
Useful diagrams are use-case for examples, component diagrams for basic
structure and activity diagrams for work flows.

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