DocBook XML and Homebrew

When I noted that I had been busy with conference planning, one angle to that I had left out is my crash education in DocBook XML, a markup language used for technical documentation.

I’ve spent close to a year circling around the question of documentation for an open source software project. Documentation is one of those maturational issues for open source software (and before we get too far, I will add that there’s no shortage of lame documentation in the proprietary software world — but that’s not the problem I’m trying to solve).

I know what doesn’t work, such as assuming documentation will naturally bubble up from the gift economy (the kind of woo-woo philosophizing up there with assuming an unregulated market will police itself). That approach yields at best a smattering of notes in a hodgepodge of formats. You also can’t just point contractors toward the project and say “write this.” I mean, you can, but it won’t work.

In the end, you need focus and direction — or as I put it in a talk a couple weeks back, some people, a plan, and a pickaxe.

The kewl thing about Evergreen is that the project is now approaching the critical mass required to support almost anything the community wants to do, including establishing a documentation project. (I don’t kid myself that a community documentation project could necessarily handle all documentation needs for an open source community, but without a project, we’ll never know what those needs are to begin with — and a community can bite off some chunks of the problem.)

Evergreen’s now got the people, and they are ready and willing to plan. But to give this project direction, it also needed the pickaxe, which is where DocBook XML comes in.

When you look at all the options for formatting documentation, and then look at the basic documentation needs of any project, you work your way to DocBook XML by process of elimination.Â Assuming your project needs a single-source, standards-based, non-binary documentation format that supports translation, reuse, and other requirements, with an active user community, and strong fee-or-free toolsets, you end up with DocBook XML or DITA. The ramp-up for DocBook XML is much less daunting than DITA (though not without plenty of daunt on its own), in part due to a couple of excellent books (and though they are freely available online, it’s much easier to buy the print books and have them parked near your keyboard for ready reference).

DocBook XML is a lot like democracy (to paraphrase some pundit): it doesn’t look so great until you compare the alternatives. Nobody thinks writing XML is a walk in the park, and after you’ve produced lengthy XML documents, you still have to transform them into HTML (or PDF), and even at that you need to style the pages so they’re all purty, because plain HTML looks so 1993. But again, after close to a year of banging my head on the wall, I get it. DocBook. All righty.

But it’s one thing to suggest using DocBook XML — and building an entire project around it — and another to actually demonstrate it in action. So about six weeks ago I realized that if I was going to make a convincing, project-energizing argument for DocBook XML — an argument first made two years ago by others in the community and repeated several timesÂ hence, with no objection but also no action — I was going to have to get serious about learning DocBook XML, if not to the level of expertise, at least to a minimal competence.

(It helped that I had been reviewing an intern’s beginning DocBook projects for a couple of months; as is often the case with teaching, I quietly absorbed more than I realized during the process of evaluating the student’s work.)

So in addition to working on the conference planning stuff, I got up at the butt-crack of dawn for weeks on end to review, validate, revise, tweak, experiment with, and otherwise produce real DocBook XML examples. After experiencing the pain of working at a DOS prompt with some free tools, I moved to a nice editor, oXygen, and that helped somewhat — but there was still much to learn (and I repeated all my examples with the free tools just to be sure they could be produced that way as well).

And then, of course, there’s the beer connection

When I started writing this blog post I saw a clear link between this and homebrewing. Circling back to that idea, I still see the similarities.

In both cases I have been learning a fairly arcane skill through books, websites, discussion groups, and iterative practice. There’s a geek level to both I enjoy; I’m not ever going to be a truly yee-haw XML/XSL cowgirl any more than I am going to open my own brewery, but I admit that the first time I got a reasonably long document to not only transform but to get styled with CSS, I did feel a wee spark of pride — similar to the first beer batch I made where I actually, and successfully, “mashed” (that is, converted malted barley into wort, the liquid that when boiled with hops and activated with yeast, eventually becomes beer).

Plus in both cases, by mastering some fundamental skills (and a domain vocabulary), I can now communicate within their respective communities. I understand terms such as single-source, transform, validate, XSL, stylesheet, FO, FOP; sparge, pitch, vorlauf, lauter, rack, mash, tun. (And to my delight, there is an XML schema for beer called, of course, BeerXML, proving that all roads lead to London.)

The ability to communicate is key; getting past that initial hurdle is crucial for learning. (Remember Helen Keller, spelling out “water”?) I may not understand every question that flies past me, but my feet have some purchase in the loam of their fields.

I don’t know. Maybe I’m just in it for the language. But these processes happening in parallel have me marveling at our capacity to keep learning, sometimes when we least expect to.

Posted on this day, other years:

Bookmark to:

Free Range Librarian