AW: [Objectbridge-jdo-dev] documentation of java packages

[Mahler T. <tho...@it...>]

Hi Frido, hi all,

> Hi,
> since I volunteered for documenting the project I'd like to 
> ask you for
> comments about a java package documentation template for 
> docbook I've made
> up during the weekend.

Thanks for your proposal!


> To put it to the test I chose the (simply structured) java package
> ojb.broker.cache.
> 
> I've attached
> - the html version of the documentation template,
> - the html version of the documentation of ojb.broker.cache,
> - a gif of a class diagram of ojb.broke.cache made with poseidon and
> - the xml version of the documentation of ojb.broker.cache.
> 

> I'd appreciate any kind of comment on the template (and the cache
> documentation). Especially I'd like to know:
> Do you think the information is relevant?

I gives a brieve and clear overview  about the cache package! I like the
Pattern and Diagram section! 

> Too much/little detail?

Maybe we need more indepth information (see my old
http://objectbridge.sourceforge.net/system/objectcache.html where I'm
explaining the softreference mechanism)
But maybe it's better to have such details not on the package level ?

> Which kind of documentation did you miss?

in my old system docs I used the following structure:
- what it does 
- how it works
- write your own implementations

For me the "how it works" part is not covered enough.
Again: maybe its better not have this kind of information on the package
level.

For the ojb.broker.cache package your apporach works fine!
But: 
1. there are packages that contains much more classes that have only little
logical coherence (e.g. the ojb.broker.util package).
2. There are packages that contain more classes that are focussed on more
than one logical component.

The package view will only provide a rough overview.
I see two options:
1. create suppackages grouped around one logical component (this will be
very difficult if not impossible for packages like the util package)
2. Introduce an additional level of documentation below the package level.
Say a "component" level.

> Is the information presented in the right order/hierachy?

I guess It depends on the focus you have if the order seems right. 
I would prefer to have the  conceptual things at the top of the document,
like in this structure:

Intent
Detailed Description
Diagramms
Patterns used
Dependencies on other packages
Hints for extending and maintaining this package
Todo

But I can imagine that others are more interested to see a more structural
overview first. 


> What do you think about the format docbook?

The docbook format is quite readable! helps to build good organized
structures.

> Thanks in advance for your comments.
> 
> Of course there is still a lot to do
> - Create a stylesheet to improve the graphical 
>   representation of the documentation (Currently it looks 
>   much nicer in the XXE editor than in the browser)
> - Customize the xsl docbook stylesheet to integrate
>   the generated html with javadoc

Where can I get the docbook dtd (or xsd) ?

cu,

Thomas

> 
> Awaiting your replies
>   Frido
> 
> PS: English is not my native language. Therefore I'd very 
> much appreciate
> any hints on incorrectly used words or phrases because I think that
> documentation should be as accurate and intelligible as possible.
> 
>