Saturday, July 26, 2008

Quality of Documentation

I spend a lot of team reading API documentation to try and figure out how a particular function works, or most likely, I use the documentation to determine how a set of API calls work together to produce a desirable outcome. On most days I don't consider myself to be one of those developers "who just gets it" so I rely heavily on the completeness and quality of the documentation to complete my task in a timely fashion. Recently I have been developing with Java during the day and PHP (more specifically Drupal) by night. I thought juxtaposing (don't you just love that word?) the documentation for the Java platform with Drupal would provide some meaningful insight for updating Java's javadoc utility.

Since Java's inception, the language has grown to an unimaginable size encompassing everything from Desktop to Enterprise to Mobile development. The javadoc utility has remained consistent throughout each release and produces the same clean, intuitive documentation today as it did several years back. In my opinion Java makes it easy to create quality documentation and the platform documentation that Sun's staff puts out is clear, concise, and objective. Enter the API documentation for Drupal.

The documentation for Drupal is not auto-generated. Someone has to sit down and document a function and then publish the documentation for the rest of the world to see. Pulling yourself away from the code to the documentation will result in a lower quality of documentation because the developer will need to make a mental note to go back through code and extract the documentation - this may not happen as scheduled resulting in incomplete platform documentation. As a result of this, Drupal's documentation is concise but does not provide a big picture view of how a particular function interacts with related functions. Despite this shortcoming, the source code for each function is included with the documentation allowing a developer to dive right into the details to figure out how to best use the function. Additionally, the documentation includes a search utility that makes it easy to find the specific function you're looking for without knowing its exact signature.

PHP and Java differ greatly in functionality so I wouldn't want to see the javadoc utility get cute with an autocomplete, search utility but I would think Sun would update the javadoc utility and provide a "web 2.0" approach to the generation of their documentation. Scrolling through ALL the classes is getting a little old. Has anyone seen a third party javadoc utility that provides a "richer" experience?