Mar 02
Documenting Castle – The Transformations Begin
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.
March 3rd, 2008 at 8:46 am
Consider me wishing …
March 3rd, 2008 at 10:34 pm
Thanks Ken – progress is being made. Stay tuned…
March 4th, 2008 at 10:39 am
Good luck Symon! I believe good documentation is utmost important to achieve an active and growing community.
March 4th, 2008 at 2:31 pm
This is great news! We have a number of projects in production built with Castle and the only criticism I have is the lack of good documentation in one place. You can normally find out how to do things but it takes a lot of searching (current docs/forums/blogs etc) before you find what you need.
If you need some help, I’d be happy to offer my services. Just let me know what you need.
Cheers
Andy
March 5th, 2008 at 4:33 am
I think that this is a good move that will pay off over time.
I did a few migration from unstructured format to Docbook format myself and this
was tedious a time…
My advice would be to spend the time to structure your content well from the
beginning. This is the best way to get maximum benefits from Docbook
Also, you may be interested to visit http://www.livetechdocs.com to review
our online collaboration service for Docbook documentation.
March 5th, 2008 at 5:00 am
yes, i feel the problem. I’m catching up.
Do you put your doc project in any repo? Maybe I can have some look and see how I can contribute.
Thanks.
March 5th, 2008 at 10:58 am
@Andy, @deman,
There’s no public repo for the work yet, but once I’ve done the basic restructure I’ll be submitting a patch to the Castle repo. As soon as that’s done I’ll welcome any help I can get on refactoring content, so thanks for your offers.
@Fabrice
Thanks for the link – very useful.