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
