Re: [xwiki-users] IDEA: API Documentation wiki

I am quite pumped on XWiki, but the lack of documentation is driving my co-workers bats (I'm already thoroughly nuts, so it doesn't bother me, except when I've got a deadline threatened by not knowing how to do something). Ludovic and Jérémi and other tireless souls are suffering with development and support, apparently, and can't get the docs updated, even though some better documentation would at least ease the support burden. Certainly, this mailing list is a major benefit, but searching the archives is a daunting task, since one needs not only to formulate a good query but also to search each and every one of a large number of monthly archives separately (from that perspective, probably a better indexer - one that would allow searching the entire archive at once - would be very helpful. Or, perhaps I misunderstand and there's already a better way? Please comment, someone, if that's the case). However, the idea that popped into my head early on this bright St. Louis Thursday morning was: What are the possibilities of Wikifying the API Javadoc pages? In this way, those of us who gain understanding of a particular part can share our hard-bought wisdom, lightening the load for everyone else. I have not delved into the uses of doclet technology, but it appears to me that a doclet could format its output as a wiki page could allow the wiki activity to take place as a supplement to the core javadoc output, which remains read-only. Further, if the javadoc output provides sufficient versioning information, successive versions of a package, class, or interface could continue to use the wiki annotations until someone noted that the new version changed something that was documented. Perhaps a scheme that recorded the version of a page that was current when the edit or comment is made would be all that was needed, so that whatever version of the javadoc was being explored, the versions of the wiki annotations valid for that version would be displayed. Using date information might be simpler, but it would be more useful to be able to tie a document version to a javadoc file version, because annotations made when a later version was current might have been valid with earlier versions, and a simple date scheme would not allow viewers of those versions to benefit from things documented later. So an XWiki template or templates could be made that would filter the Javadoc output, modifying the external javadoc-generated links to retrieve wiki pages named for the documented entities, and displaying any annotations associated with the specific entities. If Velocity isn't up to the job as-is, then (if I understand correctly) a plugin to its rendering engine could explore the DOM model and inject the wiki annotations appropriately. Another way to do it would be to write Javascript so the browser could do the work, which would probably be simpler and save bandwidth on individual page sends, but lose the benefits of server caching. The above approach would probably be instead of a doclet, which I think would take the opposite approach and drive the wiki formatting from the javadoc content. This would have the advantage of not needing any plugins or special wiki pages (maybe) and would probably be easier to accomplish but might tend to wrest control of navigation from XWiki in inconvenient ways. At any rate, the idea of making the wiki annotations independent of the javadoc pages is a major design goal and could permit anyone anywhere to put up a wiki that allowed annotating any javadoc repository, regardless of whether they controlled its content. I've discussed this far too much for one mail message, especially for one who little understands what he's talking about. If there is interest, should we put up a page on xwiki.org to develop the requirements and design? Or has someone already thought of this and it's already available?