October 27, 2004
Bad Documentation
As Jeffrey Veen points out in his article Making A Better Open Source CMS most technical documentation is badly written. His request is to "Write task-based documentation first." So much technical documentation is feature based, which is great for reference material but terrible when you're trying to get to know something.
I've seen a couple of recent example of this, libxml2 and any Oracle product you care to mention. Although I've recently been frustrated by Oracle Warehouse Builder. With both of these tools I know what I want to do. I'm looking for the documentation to show me how to accomplish it. It would be even better if it told me that my approach was a bad idea and offered an alternative. But the second rule of technical documentation is that you should never mention what your product can't do.
Instead I get tedious descriptions of each field on each preference window (OWB) or a list of supported XML standards (libxml2). With libxml2 it's just about acceptable as it's an open source project and if I want this kind of documentation I should be prepared to write it myself. But my clients have paid good money for Oracle and this kind of documentation is worse than useless at this early stage of a project. A quick plug, the PythonCard walkthroughs are a great example of how to write the kind of introductory documentation I'm looking for.
I suspect this lack of task based documentation is just a way to drive frustrated customers into the arms of Oracle Education (sorry, University) but I just think it's bad customer service. I'm not stupid; just time poor. A couple of howtos and introductory examples will go a long way towards making me productive more quickly and please both me and the people paying my salary. I don't want to wade through a thousand page reference manual thanks very much. Although it is nice to know that it's there if I need it.
I'm not going on any courses any time soon, and I don't feel inclined to write documentation for Oracle gratis, so I suggest you look elsewhere for introductory materials on OWB. But if I get anywhere with libxml2 I'll post my results here.
Posted by Andy Todd at October 27, 2004 06:49 AM