NOTE: I am (was?) a strong believer in markup. I started this work because I thought the document doesn't belong in the Docu section, and needed updating, without being aware of the potential problems with SGML. By the time I was done, I was completely horrified by this SGML business. It has it's advantages, but they come at a hefty price, so we have to be very careful when we employ it. It works OK for documents that don't require a lot of markup, like the FAQ. In fact, in that case it _saves_ on formating markup. It works nicely for documents that are essentially books (such as the User Guide, etc.) where you can expect someone to print out the nicely formatted .pdf/.ps. However, for technical documents that need to be maintained often, and are useful as a online resource that people are likely to open in an editor, it blows chunks. Now I start to understand Alexandre's preference for troff for man pages...
Hehe, I'm glad I'm not the only one who thinks DocBook is overrated - I've been wrestling with it for the past few weeks as part of writing a shared packaging metadata spec, and an automatic documentation framework for bash libraries, and I have NEVER got it to work correctly.
I've found that clean HTML with some small CSS can make a document that looks more professional (imo) and is far easier to read in a text editor, not least because emacs (and i assume vim) can apply the formatting in the tags to the text itself.
I've never looked at troff, but free software seems to need a better documentation/markup system - DocBook SGML just seems far, far too complex for doing something that is essentially quite simple.