Mar 02 2008

Open Source Documentation

Tag: UncategorizedSymon Rottem @ 12:31 am

I love Open Source software. There are just so many benefits – I was sitting here trying to think of a list and then realized that others have enumerated them, so why should I bother? That said, one of the difficulties I’ve experienced with some OSS projects has been the quality and/or availability of documentation.

One of projects that has been bothering me recently is the Castle stack, or the user reference documentation for MonoRail in particular. My team and I have spent a fair bit of time trying to grok MonoRail with Windsor Integration and have not found it to be an easy affair. This is not because there isn’t enough documentation out there but is, in fact, because it’s hard to find what you need.

Hammett has actually done a great job of writing user documentation for MonoRail (I’m sure there have been other other contributors too) but the presentation of the information that’s there (and there are pages and pages (and pages!) of documentation including examples) is not laid out in a fashion that allows a new user to easily see the relationships or get a good overview.

Because of the frustration I and others have been experiencing I’ve decided to wade into the fray and have a go at restructuring and refactoring some of the documentation to try to address some of these issues. I’m currently leaning toward a hierarchical approach with a table of contents that clearly shows the hierarchy as well as rendering in both HTML and PDF.

To that end I’ve started a thread on the castle-project-devel mailing list to try and get some feedback on redesigning the docs so they meet more people’s needs. There’s already been some great feedback but if you’ve got anything to say on the subject feel free to jump in and contribute!

« Previous Page