This is a single archived entry from Stefan Tilkov’s blog. For more up-to-date content, check out my author page at INNOQ, which has more information about me and also contains a list of published talks, podcasts, and articles. Or you can check out the full archive.

Software Documentation with DocBook, Part 1

Stefan Tilkov,

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.