A few jobs ago, I started using DocBook XML for creating documentation. I had the benefit of taking over a extraordinarily well-formed documentation set that was created by a writer who had participated in the creation of DocBook, and I learned a great deal by observing those docs and using the extremely strict command-line publishing engine.
One of the things about DocBook is that the tools that have been designed to make the creation and processing of the underlying XML easier for the writer vary widely in quality, ease of use, and completeness of implementation. By “hiding” or failing to implement the full capabilities of DocBook, these tools damage the reputation of DocBook. Almost every time I have run into a difficulty in DocBook, a more complete reading of the XSL specification or XML documentation has helped me solve the problem, unless that solution is simply unavailable in the tool or unknown to the other writers who are sharing tasks with me.
There is so much in DocBook that is specifically designed to make life easier for us technical writers to do our jobs, but if I can’t use it in your tool, you are making my life harder.
See also also: mathphrase, simplelist, menuchoice, hardware
