XPLAIN documentation

I made good progress on revising the XPLAIN documentation this week.

I had drafted some documentation (DERBY-4065) back in early February, and had received a number of helpful comments from reviewers. I kind of drifted away from the documentation when the overall DERBY-2487 change missed the 10.5 cut-off, so it was good to return to it. I'm somewhat eager to get the documentation into at least adequate shape to perform an initial commit, because right now we're in the awkward position that the code for the new XPLAIN feature is in the trunk, but the documentation is not.

Not all programmers enjoy technical writing, but I've always felt pretty comfortable with drafting my own documentation. It's taken me a while to learn how to make an acceptable attempt. Like pretty much all technical skills, as long as you respect the skill, work hard at understanding what people are telling you, and practice, practice, practice, you can learn to do this, too. Happily, the Derby project is gifted with some truly skilled technical writers who allow us to provide a complete and thorough documentation set.

Overall, I'm reasonably productive with the Derby documentation feature. We use a package called DITA, which is an awkward acronym for an awkwardly-named technology: the Darwin Information Typing Architecture. At its core, DITA is a domain-specific markup language for writing technical documentation, which of course is precisely what the Derby documentation is.

The Derby documentation survived a substantial conversion from some other format, which happened before I got involved with Derby. So DITA is all I know when it comes to Derby documentation.

My biggest gripe with DITA is that when I make a simple mistake, I often don't get a very good error message. There are two things that DITA is, in my opinion, particularly hard to deal with:

• The first is when I make a mistake which results in one of my *.dita files becoming not well-formed XML. Since the DITA build is basically a bunch of XSLT stylesheets which get run across the DITA source, and since XSLT stylesheets are among the least friendly technologies in the world when it comes to error messages, I usually just get something pathetic out of the XSLT engine. At least those error messages are pretty obvious, and I am able to figure out that I have a basic XML structure problem, and I am pretty good at matching up tags in my editor and can find them (yay Vim and auto-indent!)
• The more annoying one is when I don't quite match the DITA rules for XML schema. DITA has these rules which say things like: "the valid child elements of a 'section' tag are 'p' and 'codeblock' and 'blockquote'". But if I put some other sort of child element into my 'section' tag, I get some very strange error messages. At times I've had to resort to trying to read the DITA stylesheet source itself, but that's not often successful.

In practice, these issues tend to encourage me to keep my documentation simple, to build new documentation by copying existing documentation and modifying it, and to keep my changes as small as possible. Interestingly, these are not bad rules to live by, because small changes are easy to review, simple documentation is easy to read, and documentation which uses a consistent style and structure throughout is easy to use.

So I guess in a way it all works out in the end.