I spent a few years writing down my thoughts about how one should approach problems. If you're looking for a how-to guide, a cookbook, or a reference this book is not for you. If you want to learn by challenging the way you think, pick up a copy.
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?
Varnish is a "bad ass" new HTTP caching accelerator. It's developed by some crufty old BSD hacker and has a lot of Linux users. By and large, it has ignored Solaris. This sort of neglect isn't malicious, it is just neglect... you know: "out of sight, out of mind."
This is a reminder that our monthly meetup is scheduled to take place this coming MONDAY, August 11th. As requested, we've moved the meetings from Wednesday to Monday to facilitate some of the would-be-attendees that have contacted me out of band.
This month's presentation is titled "The essential PostgreSQL.conf". With almost 200 configuration parameters, some people might think the postgresql.conf is a bit heady, but the truth is there are only about 2 dozen that you really need for everyday use. This talk will discuss the different types of configuration settings, and give an overview of the ones you'll want to know when running PostgreSQL. Speakers for the talk are Greg Smith, Software Engineer at Truviso, and Robert Treat, Database Architect at OmniTI.
Look forward to seeing you all there!
2008-08-11 @ 6:30pm
7070 Samuel Morse Dr. Ste 150
Columbia, MD 21046