Documentation hacking

Maintaining the documentation for a project is a necessary, but often thankless task.

I’ve been going over the kdesvn-build documentation recently since there were several major changes to kdesvn-build in version 1.10 which I didn’t bother to document.

I’d only scratched the surface of the changes when I got fed up with the output that you get by default with our documentation generators (which is not meant as offense, just the way it is).

So, I took a detour and tried to duplicate my output-finessing feats that I had earlier performed on kio_man, kio_info, and kio_perldoc.

To see what I’m talking about first, consider the following:

  • Open up KHelpCenter and look at one of the installed documentation pages. (The specific one doesn’t matter, I’m just referring to styling).
  • Now look at the output of running meinproc4 with the kde-web.xsl XSLT stylesheet. (meinproc4 is the tool that KDE uses to convert the DocBook XML source to the output HTML). The kde-chunk-online.xsl output is similar. Remember that logo? :)
  • The docs.kde.org output is looking a bit better, but still out of date.
  • Finally, the kdesvn-build website has my current results at this time.

Now I am neither an artist nor a web designer but I do think that the output is starting to look better. (The content itself is still mostly out of date but I’ve at least updated the command line options and configuration options tables).

So now my question is, is this something I should work on trying to integrate back (at least for KHelpCenter stylesheets, since that output looks broken to me in the header)? I think our “spit and polish” on our user-interfacing documentation could go a lot way toward making the documentation more pleasant to use. And better yet we are outputting specifically for one of the most advanced HTML engines in the world so there’s no reason for us not to use every useful feature if it makes the output nicer, no?

Oh, I changed the git checkout/update procedure a week or so ago in trunk, if you’re not testing it I would appreciate it if you could test so I can do the next release this upcoming week without me being the only one to use it. ;)