I really enjoyed listening to Addison Berry talk this afternoon at OSCON 2009. She has clearly thought a lot about the social aspects of getting folks to create and maintain documentation for Open Source projects. I learned quite a bit from her talk and hope to learn from the rest of you as we go along.

My own focus tends to be on technological solutions. Having used a variety of documentation tools, I think I have a notion of how to build a generalized framework for mechanized documentation that I would want to use. I'd love to get some feedback on my approach, however, based on others' desires. As Addison correctly points out, Open Source documentation needs to be a group effort; if my framework only pleases me, it won't get much action...

Looking at Wikipedia's Comparison of documentation generators page, it's clear that there are lots of tools around. However, I don't see any that are Open Source and handle (specifically, parse) a wide variety of languages. I'd like to address this problem eventually, even if my initial efforts are limited to Ruby.

Another failing, IMHO, is the fact that these tools create read-only results. If the reader wants to ask a question, make a comment, or correct a typo, s/he will typically need to grab a copy of the project's source code, find the right file, generate a patch, and submit it through a bug-tracking system. If Wikipedia required this level of commitment, it would have (deservedly) died on the vine...

So, at minimum, I'd like a tool that parses program source code and comments. It would also be nice if it did various kinds of code quality analysis, generated useful metrics, etc. Basically, anything that a computer can do in an unsupervised manner to gather information from the code base...

It should then feed both the original code and the derived information into a wiki, allowing humans to annotate and discuss the results, contribute their own observations, etc. Ideally, the system would be able to send this information back to the original projects.

I would also like the system to be able to integrate information from multiple sources. The typical Rails project, for example, might use a number of Gems and Plugins. Wouldn't it be nice if the user could specify which ones are of interest, causing the system to present a customized collection of APIs?

Finally, I'd like users to be able to use the wiki as a programmable report generator. If a user thinks of a new way to analyze or present information, s/he should be able to script it up and have the wiki generate the results.

If you find these ideas interesting, please take a look at my working notes on Ontiki, an experimental framework for mechanized documentation. In particular, look at PARSE, my initial use case. Then, let me know where I'm going off the Rails :).

-r