> From the asciidoc web site if I understand correctly asciidoc can generate not only single page documents, but also "website" as well. Is that right? (multiple documents with navigation btw them?)
You can do this, but it involves transforming Asciidoc into DocBook first to generate a multi-page document/site. This is quite a complex toolchain (which is why you need so many packages), so I would prefer something simpler.
> Or should we not have the generated docs in trunk? (I find it useful for ppl checking out the source, but it does add additional small burden to commiter).
It is useful, but I think the reason we stopped doing this in Hadoop was because of the extra burden to generate Forrest docs. If the burden is small then I think we should check in the generated docs (this is why asciidoc is probably not a good choice).
I spent a bit more time looking at other Apache sites, and quite a few do use exported confluence to good effect (e.g. Camel, Jackrabbit, Sling, Wicket), but the limitation, as noted above, is that only people who have signed an ICLA can edit documentation. This sounds like a barrier to me, but perhaps I'm over optimistic about how much documentation is contributed? It's possible for anyone to add comments to a page though.
So I'm tending to think we should take the Cassandra route - have a minimal website (one page?) as a jumping off point, with versioned release documentation in javadoc (with top-level docs in the overview file - there would be one for core and one per service - or even extra plain HTML files, see http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/javadoc.html#unprocessed), and a link to the wiki for further information. We could introduce a different documentation system at a later point if we wanted more structured documentation outside javadoc. This could be another confluence wiki, or sphinx (which looks easy to install, and the markup is reasonable), or something else (!).