Mar 02 2008

Documenting Castle – The Transformations Begin

Tag: UncategorizedSymon Rottem @ 11:24 pm

It has begun. The process of transforming the Castle user guide and getting started documentation to DocBook format is underway.

The process has so far involved writing a (truly and stupendously horrific) XSLT that transforms the selected parts of the original XML used to generate the Castle website into DocBook format, the creation of a simple batch file feeds all those XML files in each sub-folder to msxsl.exe with the XSLT sheeet to perform the transformation.

I say the XSLT is horrific mostly because my skills in the realm of XSLT authorship sucks like a vacuum cleaner and I’ve had to kludge something together without really knowing what I’m doing…

The really interesting part came from attempting to transform the HTML tables that were embedded in the original XML into the DocBook table format which doesn’t bear nearly enough resemblance to each other as I would have liked. After banging my head against the wall for a couple of hours the problem was solved using parts of someone else’s work who has much better XSLT skills than my own. See? I have no trouble resting on the shoulders of giants.

Regardless of the complete mess that does the processing, the damned thing works. It seems to have created documentation fragments that can be validated against the DocBook schema with only a couple of small exceptions. Yay!

Next step is to start reorganizing the information into logical groupings to present as chapters and subsections.

Wish me luck.


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!