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? brain[sic] -----Original Message----- From: Erwan Arzur [mailto:earzur@gmail.com] Sent: Thursday, March 16, 2006 3:27 AM To: xwiki-users(a)objectweb.org Subject: Re: [xwiki-users] Hs_err_pid XWiki 0.9.840 + tomcat 5.5.9 + vm1.5.0_06 Hey Leonard, yes i'm taking care of xwiki.com. Yes recently it has been a real PITA, most of the instability problem were due to comment spammers hitting us hard. Since last saturday we are running mod_security on our frontend servers and i do not have to check every hour if one of those assholes took us down again ! what a relief ! (take care with the latest gotroot rules for mod_security, our apache ate all available memory then had to be killed - blacklist.conf is too big, i don't use it anymore) I'll check the system requirement route, but we don't experience VM crashes very often. One hint about your particular VM crash. As every thread appears to be locked when it happens, it seems to be garbage collecting related, and i'd investigate tuning the new generation and related stuff. I've got this already on my TODO list and will let you know the outcome. I posted a note about this on my weblog (http://www.arzur.net/index.php?English) where i suggest every spammers taken to courts should pay a check to the OSS anti-spam project of his choice. Another way of financing OSS. Most of the good tools in this field are open source anyway. SpamAssassin, SpamBayes, mod_security, gotroot.com ... come to mind. Erwan On 3/15/06, Leonard Lin <leonard.lin(a)unic.com> wrote: