|
|
|
Sponsored Link •
|
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:
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.
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.
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.
Those key questions again. Put yourself in the position of someone
who's encountering your stuff for the first time.
Have an opinion? Readers have already posted 2 comments about this weblog entry. Why not add yours?
If you'd like to be notified whenever Eamonn McManus adds a new entry to his weblog, subscribe to his RSS feed.
 | 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. |
|
Sponsored Links
|
Digg
del.icio.us
Reddit