Nelz's Blog

Mah blogginess


I had this idea a while ago, but it popped back up into my brain when working on my "Participation Culture" entry…

In the past I have felt that JavaDoc is just too… one-way.

The format is great as a one-way, generated-from-code outlet for programmers… But this ignores the benefits of the population at large. If some people spend their free time working on entirely new frameworks, I’m sure there’s a larger section of people who are willing to share in the enrichment of the documentation as well.

So, why not change the one-way broadcast to a two-way conversation?

My original thought was to have a JavaDocWiki site, where I’d enable some type of processing against a given JavaDoc set. This processing would decorate the pages with whatever ‘dashboards’ would be helpful, and links to an interactive Wiki-stle page for each class/method/variable…

But, the fault with this course of action is that the interactivity is at a brand new site. Yes, this site could still serve the basic documentation needs just as well as the originating sites, but it would still be a whole new site that people would have to reference.

I got to thinking… Why not just ‘decorate’ the original source files?

Maybe a GreaseMonkey script would be able to decorate the original source codes, slurping in the interactive dashboards and linking out to a host site for the interactive elements? (I haven’t audited GreaseMonkey≈’s capabilities to see if this is even possible yet, but it offers some intriguing possibilities…)

I guess in either case you would end up depending on host sites for the interactive bits, and you might end up with a busy ecosystem of different hosts being the ‘authority’ for different versions or sections of the code. Another concern would be migrating from version to version.

Ideally the documentation would end up with high enough quality that the original source developers would be able to slurp up the added doc for inclusion in the actual source code.

I also think this model might work for other auto-generated code documentation. Example: RDoc.

UPDATE (16 May 2008): It turns out, someone else had this idea too. Check out