Monday, September 6, 2010

On Open-Source Documentation

So I am sitting in the office. I've spent the morning reading documentation on the Shibboleth middleware I am implementing while I wait for another department to build my hardware. Outside it is a cool, clear day.

In here, my levels of frustration have waxed and waned through the morning. Why is open-source software so poorly documented? Especially open-source software that relies on other open-source software. Implementing this thing has been like trying to put together a jigsaw, only all of the pieces come from different puzzles with different pictures on the boxes.

Change one piece and you need to trim that puzzle piece with a pair of scissors. Now I am a fine one to talk; I am sure that more that a little of my documentation is sub-par. But my expectations were higher than that when working with this product.

Were my expectations unrealistic? I went back and forth on that for a while, but what amazed me was that thinking back on the commercial software I have used in the past, I realized that more often than not, their documentation sucked, too. I am most familiar with Cisco products. Before my exile to project Siberia, I used CatOS, IOS, WLC software, Cisco ACS, CiscoWorks and so on. Invariably, the documentation for the software sucked. Especially if you wanted to do something which is not quite turn-key. Not that the products had limitations in the area I was investigating, mind you, just that the documentation was geared towards the turn-key solution.

Thus the realization dawned that the documentation didn't so much suck, it was just that I wasn't the audience for the easy-to-find documentation. The documentation needs to address the majority of cases, not the exceptional outlier. This is fundamentally different from internal documentation often demanded by management - highly specialized to the specific implementation you are doing, so that systems can be replicated. In some cases documentation so detailed that the network could be rebuilt by the last surviving janitor after the nuclear holocaust.

So after lunch, I am going to cut the documentation some slack, and lower some of the expectations. Sometimes you have to do the heavy lifting yourself. And maybe I'll put my implementation notes up on the web for someone else to whine about.

1 comment:

  1. I've found that poor documentation certainly isn't limited to ICT bits.