A tale of bad documentation

I am a programmer by day for a small software company. By night I write open source software. I guess I like to program.

I once submitted a patch to an open source program called XML Copy Editor. It was small. Soon afterwards I volunteered to perform a small task and was given developer access to the source repository. I continue to correspond with the developer although I've only made that one original change to the programs source code.

My latest non code contribution was helping the author replace MSXML with Xerces on Windows. I originally expected to have to fight with Xerces, but by dumb luck the first thing I tried worked after a bit of tinkering. The reason that the programs author had trouble using Xerces on windows was not because of bad code or bad make files. It was because of bad documentation.

Because of bad documentation many hours were wasted by him that could have been dedicated to making XML Copy Editor better, or any other task he chose to spend his leisure time on. Because of bad documentation XML Copy Editor has fewer features than it could have. Because of bad documentation I am writing this post.

Now I decided to allow some good come out of this situation. As you all know, I decided to use this as a lesson delivered by the blog article you now read. In addition, I shared my story with the Xerces-C developers mailing list and offered to correct the situation.

Now if you read my email and the documentation I refer to, you will probably come to the conclusion that the documentation is quite good, except for this one oversite. You would be correct. However, the oversite was for common usage scenario, and caused significant harm to one developer and his user base in terms of wasted time. Since the documentation fails to cover the usage senario I care about, the documentation fails to address my needs. Therefore I could have been alienated by the documentations small oversite.