July 17, 2003
Software Documentation with DocBook, Part 1
The document for iQgen could use some overhaul, both in terms of content as well as form. As usual, that's the task nobody is that keen on doing, so it's left to me.
Thinking about the right way to do this, I decided to move everything to DocBook (it's XML following a self-made schema right now). While I'm at it, I thought I might as well document tools and approach I use as I move along.
The Software Documentation Weblog is a nice starting point for some information related to DocBook (apart from official book site). The DocBook Open Repository Project contains XSL (and DSSSL) stylesheets to generate different output formats from DocBook instances (the DocBook DTD itself is maintained by OASIS). The main benefits of DocBook for me are:
- I don't have to invent new XML constructs, since DocBook defines a whole bunch of them
- There is a huge number of stylesheets that can transform DocBook instances into the most important output formats, being, for me, HTML, PDF, MS HTMLHelp and JavaHelp
- I get to play around with a bunch of new stuff ;-)
Working with the documentation is also a nice excuse to try out <oXygen/>, which I wanted to do anyway.
Stefan Tilkov wants do do documentation for a software project with DocBook. The first post sound very optimistic, a later one a bit pessimistic. He is struggling with finding a good XML editor with integrated support starting XSL transformations. Besi...
Read more in Choosing the right tool for DocBook »