[Edocs-development] Rules to follow for requirement analysis and design documentation

[Sergio R. <sra...@ti...>]

Team,

based on some Derek's observations about the way we can build project
documentation I've decided to radically
change the way project's documentation is written now and for the future.

The way to write documentation is to use XML with an appropriate XSL file
and an ANT task to process the builds of
a series of HTML files that we and other people can read with a simple
browser.

This approach gives us:

1) Flexibility in writing documentation without platform specific issues
2) Less space required
3) Uniform project wide docs layout given by a common XSL file and a common
stylesheet.

First of all the documentation directory's name has changed from
"documentation" to "doc". I've asked Sourceforge team to delete
the oldest one.

The new directory has a subdir called ad that is the root of the Analysis &
Design documentation. There we have an index file
that links all the 6 application areas: storage architecture, search engine,
security, system setup, interoperability, web interface. Under there
we have one subdirectory for each one of the five areas.

doc
    |
    ---- ad
             |
             ----- storage
             |
             ----- search
             |
             ----- setup
             |
             ----- security
             |
             ----- interoperability
             |
             ----- web_interface

Every subdirectory contains core A&D documentation for that specific single
area. Every subdirectory is organized with an index file
and a "uc" subdir where we have use cases for that specific area. The name
of the use case documentation file is like the identification
number of the specific use case (ex. for A1. Add new user the uc file will
be named A1.xml and so on). Under the "uc" subdir we'll
have a "diags" subdir that contains all the UML diagrams needed for the
specific application area (use cases, sequence, collaboration and so on).
All the diagrams will be in PNG format. The naming convention for every
diagram will be

<diag_type>_<use case id>_<progressive>.png

So for example the first use case diagram for A1 will be named UC_A1_1.png.
I suggest for <diag_type> to use
UC for Use cases, COLL for collaboration diags, SEQ for sequence diags, ACT
for activity, CL for class diags, DOM for
domain diagram.

So if we consider the use case A1. Add new user it will be described in the
file A1.xml contained in doc/ad/security/uc. The use case
contains a use case diagram that will be named UC_A1_1.png contained in
doc/ad/security/uc.

The processing of the xml files to obtain HTML will be done using the ant
task compile.manuals. The resulting HTML files will
be put under the path target/doc/ad and so on (same struct as above). The
XML files will be composed using some simple xml
elements. You can take a look at the files already present to have some
example on how to do that. The use case A1 really contains
diagrams.

So take a look. The original word document has been eliminated and all the
UCs has been migrated in this new format (also
the Derek's ones). Derek what do yuo think about that?

Also I would like to have feedbek on the tasks I've assigned. Derek,
Ashwini, Anton, Dobb can you give me news??
Piotr, can you take a look at the files and give proposal for a much better
layout. It maust be simple, without graphics (just
our logo, but much better navigations mechanisms.

Regards

Sergio