Monday, August 6, 2007

Collaborative Documentation Web Application

A web application that can take documentation, perhaps in XML or another format such as Doxygen's and display it, but the add-on value would be that it would allow users to add comments to any part of the documentation. The application would provides features that would make it very easy for the documentation writers upstream to know about new comments so that they can integrate useful ones into the documentation.

Common errors that are discovered by the users where it would be useful to have an easy way to report include:

  • Spelling mistakes

  • Typo's

  • Broken links

  • Examples that don't compile

  • Straight out docs that don't match the behavior of the function code

  • Documentation that could be worded better

  • Undocumented behavior



Beyond those users are able to provide quite a bit of value add to documentation when presented with a way to such as:

  • Example usage

  • Workarounds

  • Performance tips




PHP's php.net website was the first I saw that had this built in feature. A good example is str_replace. The users provide a lot of extra value. The problem is that currently php.net is for php and same goes for the few other collaborative documentation sites that are out there. Compare this to the hundreds of Doxygen generated sites out there there this is a project that would have a lot of users.

No comments: