The SquizLog

I had a brief flirtation with DocBook, even did some actual documentation with it. DocBook is impressive and the thought of ensuring the longevity of the textual artifact by coding it in XML is enticing; but you do so at the cost of editability. Damn shame. Hope you come to a different conclusion.

Editability? What's more editable than plain text xml files? I guess some wiki-like syntax might be simpler, but there's a lot of semantic info about the structure that can't be captured without a markup language of some type. Maybe there's something that could be done in this area with docbook lite.

The documents are certainly too tough for non-technical users to author; that's always a source of problems. I tried Adobe Framemaker to see if it work for some of our users to create docbook documentation, but it's really not appropriate for that. There just doesn't seem to be a transparent way to expose the depth of the metadata that makes docbook so valuable without having authors be familiar with the DTD.