The Linux Documentation Project, DB2, XML, and nostalgia

Posted on Mon 17 September 2007 in Databases

I took a walk down memory lane this evening. I thought I might as well bore you with the details.

One of my first forays into the open source world was to participate in the Linux Documentation Project (TLDP). At the time (circa 1999), I was working for IBM as a technical writer for DB2 database. IBM was releasing DB2 on the Linux platform, I was part of the pre-release testing team, and I had turned to TLDP to provide me with an introduction to the world of Linux as a total n00b. It was a godsend of information.

When DB2 was officially released on the Linux platform, it only officially supported a handful of distributions. Given the normal technical writing and release cycle, the officially supported versions of the distributions were woefully out of date in the official documentation. That, and much of the required installation and configuration information was either missing, or wrong. Don't lay any blame on the people involved; that was just the way that the release process (including translation into umpteen languages that were all available on release day) forced the end product to be. My focus was on application development, but I had to get test environments set up so I could ensure what I was writing actually worked (that's the way I roll as a tech writer). Of course, I chose an unsupported-by-DB2 but much more current distribution (Mandrake Linux 5.3 "Venus" I believe) simply because it would install on my hardware, when Red Hat 5.2 would not.

It struck me that my install experiences would help other DB2 users as well. I realized it would also give IBM a way around the barrier imposed by the restriction that the official documentation for a given release was published once per release - no updates. By contributing a DB2 HOWTO to TLDP, I would not only be able to provide documentation on the distributions that people were actually using, I would also be able to update the HOWTO as circumstances warranted. My manager supported the project, and helped me stickhandle some obstacles. The result, I believe, was beneficial all around; I contributed some code to TLDP to help improve the PDF output and helped mentor some TLDP n00bs; DB2 got some usable documentation when it really needed it; and I had the opportunity to learn a technical writing DTD that made sense (DocBook) and play with an impressive open-source publishing toolchain.

Over time, my friend and co-worker Ian Hakes picked up the ball and drove the next iteration of the DB2 HOWTO with my help. It has been over a year and a half since I left IBM, so I haven't paid any attention to the DB2 HOWTO. Recently, however, as I was playing around with an updated version of the DocBook toolchain, I discovered that Ian has released a brand new version of the DB2 HOWTO to cover installation of DB2 Express-C on various distributions. He included a touching tip of the hat to me, as well. What a swell guy!

On one hand, I'm not sure that TLDP has nearly as much of a mandate as it did eight years ago. There are scads of books, a handful of good magazines, blogs, wikis, and web sites all publishing information about Linux these days. On the other hand, there's something to be said for a corpus of documentation maintained and edited by volunteers who just want to get information into the hands of people who need help -- without compensation, without publicity, and generally without thanks.

So, given how much TLDP has helped me - thank you, TLDP volunteers. And thank you, Norm Walsh and the entire DocBook community, for providing an open-source publishing toolchain that starts with semantic XML and results in professional-looking documentation.

P.S. I made another commit to the DB2 HOWTO tonight - just balancing out an XML element that was missing to return the document to valid XML state. And let me tell you, it felt good!