The Artima Developer Community
Sponsored Link

Dr. Dichotomy's Development Diary
It's not enough to say what it does
by Eamonn McManus
July 23, 2004
Summary
All too often, developers think that documenting their new creations just means writing a detailed technical description of what it does. In a sense, they're explaining things to themselves. But what you really need to do is explain things to someone who's coming across your stuff for the first time.

Advertisement

I recently completed an interesting self-imposed task: writing package.html files for all of the packages in the JMX API (javax.management.*). Up until now, each package description looked like this:

Package javax.management Description

Provides the core JMX classes.

Well, that's useful.

When the JMX API was a separate API, this was perhaps acceptable. If you were reading the documentation, you had probably gone to the trouble of downloading and installing it. You already knew what it was and why you were interested in it.

But now, the JMX API is going to be part of the standard J2SE platform. So what's your reaction going to be if, out of curiosity,  you click on the javax.management link? You'll see 66 interfaces, classes, and exceptions, and that one helpful sentence to tell you what they are about. Then you'll go and look at something else.

In fact, all the information you need to know is present in that HTML set and in the separate PDF specification document. But where do you start? It is not enough for the information to be present. It must be accessible.

Making information accessible means putting yourself in the position of somebody who's learning about it for the first time. The key questions are:

In the case of the JMX API, the answer to the first question is simple. They'll look at the package documentation for javax.management first. So it better contain good answers to the other questions.

The new package summary begins with this text:

The Java Management Extensions (JMXTM) API is a standard API for management and monitoring. Typical uses include:

The JMX API can also be used as part of a solution for managing systems, networks, and so on.

The API includes remote access, so a remote management program can interact with a running application for these purposes.

The idea here is that, before launching into a detailed discussion of what is in the API, we explain what the API is for. Maybe the person reading this doesn't have a very clear idea of a management system is. Maybe they do have a clear idea, but it doesn't correspond to what this API does. So straight away we provide a quick summary. If you are just curious, or if you want to know whether the API can address a specific problem you have, or if you wonder which of your problems it might address, this simple text should give you some idea.

The text is deliberately brief. The more you write, the less people read. It uses bullet items, because people tend to look at those first. The full text also includes many subheadings, for the same reason.

Examples

The remaining text then takes the reader on a brief tour of the most important concepts and classes of the API. The information it includes was already present in the JMX specification. If you needed to know how to write a simple MBean, you could figure it out after studying the specification. But why should you be forced to do that? Everybody beginning to use this API will need to know this, so the new text includes examples. Examples of what the interfaces might be used for, and code extracts to show them in use.

It's hard to overstate the importance of examples. Everybody thinks in terms of examples. Don't believe anyone who tells you they don't. Yet so much API documentation is written as if it were sufficient just to say what the interfaces do. As if the person writing the specification were just beaming their understanding directly into the reader's mind through the magic words of formal language. (Of course, lots more API documentation doesn't even say what the interfaces do, in any but the vaguest terms.)

Examples serve as a high-level specification. If I give an example of the naming conventions that the JMX API parses for its Standard MBeans, then that tells 99% of the users everything they need to know. The full specification is still necessary to cover the details, but it can be buried deeply in the documentation.

Examples give readers context. When they read the definition of an interface, they can see how it relates to the example. They can imagine modifying the example in various ways and see how the interface matches those changes.

Examples also act as a sanity check for API designers. If you can't think of an example for your interface, then why is it there? If the only example you can think of is incredibly far-fetched, couldn't you redesign things so that a simpler example is possible? If you include a code extract in your example, and it is complicated, then maybe that's a sign that you should adjust the API so that simple examples are simple to code. There were a couple of instances of this in the examples I wrote for the JMX API, which will be useful next time that API is revised.

Putting things where people will find them

In fact the Reference Implementation for the JMX API has always contained examples. If you unpack it, you will find an examples subdirectory. But don't expect people to look there. People will look at the Javadoc, and they might look at one or two introductory documents like READMEs, but for the most part they won't go burrowing around in the directory structure.

Furthermore, the existing examples serve a slightly different purpose. They are complete, self-contained programs that show the API in action. This is useful too, but not for the person consulting the API documentation. That person wants to see examples in the text they are looking at. They don't want to have go and look somewhere else and juggle two sources of information at once. And working examples contain extraneous detail that distracts from the key points being communicated.

As a general rule, there should be one starting point for someone working with the documentation. It should be an expected starting point (ideally the top level of the generated HTML), and it should provide an obvious path to the other information. The Javadoc tool already works well in this respect. From the top-level HTML, there are links to the classes and subpackages.

Summary

Those key questions again. Put yourself in the position of someone who's encountering your stuff for the first time.

Talk Back!

Have an opinion? Readers have already posted 2 comments about this weblog entry. Why not add yours?

RSS Feed

If you'd like to be notified whenever Eamonn McManus adds a new entry to his weblog, subscribe to his RSS feed.

About the Blogger

Eamonn McManus is the technical lead of the JMX team at Sun Microsystems. As such he heads the technical work on JSR 3 (JMX API) and JSR 160 (JMX Remote API). In a previous life, he worked at the Open Software Foundation's Research Institute on the Mach microkernel and countless other things, including a TCP/IP stack written in Java. In an even previouser life, he worked on modem firmware in Z80 assembler. He is Irish, but lives and works in France and in French. His first name is pronounced Aymun (more or less) and is correctly written with an acute accent on the first letter, which however he long ago despaired of getting intact through computer systems.

This weblog entry is Copyright © 2004 Eamonn McManus. All rights reserved.

Sponsored Links



Google
  Web Artima.com   

Copyright © 1996-2019 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use