I’ve been writing docs for Reconnoiter. I selected DocBook for two reasons. First, I hoped that number of polished documents I’ve seen written in DocBook would mean that if this manual grows in size and usefulness we might be able to achieve some polish “on the cheap.” Second, our open-source site has a really nice automated systems for auto-publishing project documentation… if it is in DocBook. That said, DocBook is a complete pain in the ass. It isn’t broken or bad, but it really gets in the way of writing the documentation. There are so many marks, and their use is specific and contextual. I understand that there is a reason for all the marks (provide semantic meaning to what you write), but you must be fluent with the entire specification and practiced to achieve anything useful with DocBook.The fact that DocBook uses XML is tiresome. XML itself isn’t bad. Despite my extreme ineptitude and writing XML that will lint, I’m rather fond of XML. It just so happens that because I’m fond of XML, the software product I’m using leverage XML in configuration files and support files. This leaves me in the painful position of documenting XML in XML and now I have all sorts of escaping requirements that I’d like to not use CDATA for (cause I want to lint them).Now, enter the next phase of inconvenience (read: torture). Because Reconnoiter is modular, the documentation for the modules needs to be programmatically accessible to assist with online configuration validation. To achieve this, we choose to put the module docs right next to the module itself and from there we produce DocBook snippets for inclusion in the reference manual. The module documentation is in XML, the configuration of the module is in XML, the configuration of Reconnoiter is in XML, DocBook is in XML… We just need to take them all and compose documentation (with all the right escaping). Enter XSLT: a tool of torture. Now, I’m intimately familiar with the inner workings of XSLT transforms from the C side hving worked extensively on FastXSL for PHP, but actually writing XSL documents is something I strive to avoid. This conflicts with one of my core principles: “use the right tool for the job.” The entire purpose of XSL is to translate XML documents into other documents (XML being a first-class target). XSLT it is.I’m left in a position of documenting a component of the system in XML (easy enough) and then writing XML to run on the first XML (which contains both raw docbook XML snipets that cannot be escaped as well as XML configuration snipets which must be escaped) to produce a second XML to be included by a larger XML DocBook document. This now conflicts with another of my core principles: “K.I.S.S.” (I’ll note the wikipedia entry says it’s used on the Internet in a way that implies it started there. This term far far predats the Internet. Oh, and the last S is definitely “Stupid”).Now, I don’t much like DocBook because of my lack of fluency and its interruptive influence on the process of writing documentation. This is mostly my shortcoming, not DocBook’s. I never can seem to write an XML document that lints the first time around… Again, my shortcoming, not XMLs. XSLT is an “ornate, complexly syntaxed, functionally limited shortcoming.” I really hate XSLT. Here are someone else’s reasons. They are good, but mine reason is that my tasks are usually simple and there is no simple variant of XSLT that can do the job; i.e. the jobs I do are simple and I think XSLT’s cost (learning) rarely outweighs the value.This makes me think that most documentations should be written by a tag-team. A documentation writer that writes in something like POD (the ultimate in K.I.S.S.) and a documentation compiler that consumes that and produces all the required DocBook stuff. Within a company, it’s easy to put this process in place, but it’s hard to get this sort of collaboration on open-source projects.It’s hard enough to get an engineer to write good documentation. Painful, persistent and minor technical obstacles really don’t help. There should be a really kick-ass opensource docbook editor for technical manuals that integrates with subversion and mult-file layouts. This won’t ever make XSLT better, but it would sure allow engineers to concentrate on content instead of markup. Anyone know of one?