The Artima Developer Community
Sponsored Link

Weblogs Forum
It's not enough to say what it does

2 replies on 1 page. Most recent reply: Sep 1, 2004 12:24 AM by George V. Reilly

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
Previous Topic   Next Topic
Flat View: This topic has 2 replies on 1 page
Eamonn McManus

Posts: 20
Nickname: dichotomy
Registered: Apr, 2003

It's not enough to say what it does (View in Weblogs)
Posted: Jul 23, 2004 10:33 AM
Reply to this message Reply
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.

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

Package 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 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:

  • What will they look at first?
  • Why will they be interested in what they see?
  • Where will they go from there?

In the case of the JMX API, the answer to the first question is simple. They'll look at the package documentation for 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:

  • consulting and changing application configuration
  • accumulating statistics about application behavior and making them available
  • notifying of state changes and erroneous conditions.

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.

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.


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

  • What will they look at first?
  • Why will they be interested in what they see?
  • Where will they go from there?

Kristian Dupont

Posts: 22
Nickname: chryler
Registered: Dec, 2003

Re: It's not enough to say what it does Posted: Jul 25, 2004 2:56 PM
Reply to this message Reply
You are absolutely right.

Doxygen and the likes are fabulous tools but I simply *hate* following a link to "documentation" of some library or other source code that I am interrested in and find that it was autogenerated from the code.
To understand code you have to become familiar with the paradigms and terminology that is used. This rarely shows from a list of classes and methods.

George V. Reilly

Posts: 2
Nickname: georgere
Registered: Sep, 2004

Re: It's not enough to say what it does Posted: Sep 1, 2004 12:24 AM
Reply to this message Reply
> Examples also act as a sanity check for API designers... 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.

This sounds a bit like Test-Driven Design, where you write a test first that doesn't work, then write code that makes the test work.

Example : test :: API : code

Flat View: This topic has 2 replies on 1 page
Topic: Pragmatic Programmers sponsor Rails identity! Previous Topic   Next Topic Topic: Thoughts on Change at 35,000 feet

Sponsored Links


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