geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andy Jefferson <a...@ajsoft.net>
Subject Re: documentation
Date Wed, 13 Aug 2003 15:01:58 GMT
On Wednesday 13 Aug 2003 15:51, Felipe Oliveira wrote:
> i agree with you amar...good documentation and good UIs will make a
> difference against jboss and others. it will attract novice users that
> feel the other options lack good support in these points.
>
> Nanduri, Amarnath wrote:
> >Has any thought been given to the documentation of the project? By
> >documentation, I meant both the source code and the configuration and
> >internal workings. If not, I would rather we start putting emphasis on
> >it from day 1 to ensure that we put together excellent documentation.
> >Any thoughts on this? Thanks

Look where competitors are perceived weak ... the lack of transparency of 
their systems. Amongst the types of docs
a). code documentation. You are using Maven and so you have adopted a series 
of reporting tools (under the Project Reports section on James's geronimo 
page). Checkstyle, PMD, JDepend, JUnit, CVS, Javadoc, Clover, etc.

b). You can extend your Maven website generation to use the Maven 
"multiproject" plugin, and put docs specific to each module under the xdocs 
directory of that module - and add a navigation so you can go down to each 
module,

c). Usage documentation. Needs to focus on how the user thinks of your system 
- some users think functionally (i.e of a module), whereas others think of a 
particular task (e.g deploying a war). So you need documentation to be 
bi-directional. The first set of docs (for each module) can be in the xdocs 
subdirectory of each module. The second set you could put at the top level in 
the xdocs directory. The second type ('howto') will become more apparent as 
things fall into place.


-- 
Andy


Mime
View raw message