jastrachan | 15 Apr 05:15 2004

Re: documentation frustration

On 15 Apr 2004, at 04:00, LARSON, BRIAN (SBCSI) wrote:
> Will Schenk said:
>> However, it's been a very frustating experience, mostly
>> because I have no idea
>> where to look for any documentation/examples.  The archives
>> for this list are
>> extremly helpful (run the latest shapshot! run the latest
>> shapshot! ;) and
>> http://www.ociweb.com/jnb/jnbFeb2004.html is a good orienter,
>> but for the most
>> part I'm lost.
> You're right.  Everyone agrees that the documentation should be
> improved.  It does continue to improve.  Maybe we need to make it 
> easier
> to contribute documentation so that people like you who figure out
> things which are not adequately documented can contribute improved 
> docs.

Incidentally I've been experimenting with using Confluence (a wiki 
tool) for all the documentation on the website of another couple of 
codehaus projects (e.g. http://activemq.codehaus.org/) and so far its 
going well.  To see the 'document management' side of this website, try 
looking at this link 

Once some of the kinks are worked out - and some of the gaps between 
the maven-generated documentation and the wiki are worked out - I'd 
like to move all the current website over to Confluence, so it'd be 
real easy for anyone to edit/add comments/contribute to the 
documentation etc.

The aim is for all documentation to be live - then whenever something 
code-centric is committed to CVS then any maven-generated stuff is 
redeployed and rendered nicely.

Also then we can harvest the old wiki (some of which is now stale) and 
have a single, unified documentation set in the wiki.

A nice side benefit would be we'd get a little groovy blog like this...


for announcing things for folks who are way too busy to track the mail 
lists - and we could easily add things like a 'tip of the day' section 
as well as an easy to create/maintain FAQ system...


Thinking about the JSR - I wonder if we could write the language 
specification, in a separate space on the wiki too?