The Java Dudes cartoon on the back page of JDJ has boosted my reputation as someone who likes the API documentation for the core Java language. It's easy to navigate, it's quick, and it answers some of those common Java-related questions. There are a couple of questions that are constantly on my mind. First, with such a rich resource of information, why do programmers (of all abilities) whom I have contact with fail to look at the API docs in the first place?

One theory is that there's a lack of detail about using some of the methods listed. Now, I know of sites like Java Almanac (www.javaalmanac.com) that provide good examples on how certain methods are used, but I do think these should be woven into the general API docs. Beginners would benefit from having a resource on their own system that would also provide general examples on how that class or method should be used without having to sift through the example code (can you remember when you last looked at it, I can't!).

There are small snippets of examples within the main class explanation; my goal would be to have a small code segment for the methods as well as a quick indication that I'm going in the right direction. The more that's added to the API as time goes on, the more that'll have to be documented. Obviously, there's a whole book-writing segment of the community who makes a living from bundling these examples into API reference books. Patrick Chan (and his team) has done an excellent service for the Java community with the Java Developer's Almanac and has obviously spent a lot of time looking at all the classes (hey, if you want music MIDI class information, it's in there). The same is true for David Flanagan, who wrote the Java Nutshell series for O'Reilly; he even wrote Java Examples in a Nutshell as the API reference was so large it was pushing examples out.

Apart from increasing the size of the download of the documentation, I don't see why Sun can't improve the example usage of methods with all the APIs regardless of whether it's J2SE, J2EE, or J2ME. The API docs should be the first point of reference for the programmer to help solve the problems. The more people I talk to, the more I'm reduced to pointing to the API docs (mainly on IRC). Now it's either down to plain laziness or the information that's presented is not up to the job. I agree that there are a number of Web sites with more information, but it becomes a major task to search these sites and get the required information. I'm finding that students in teaching establishments tend to ask questions without consulting these sites.

If anyone from Sun Microsystems is reading this, their blood pressure is probably rising on the simple issue of time management and what to include and what not to include, if any of my small wishes come true. What we could do is pick a couple of methods and write an easy example. These would then be checked and verified by Sun (because we don't want anything going into the API docs) and then it could be released. Now I do know that this means changing the JavaDoc statements within the actual class code, but most people install Java with src.zip installed, so I think it's worth thinking about.

I've looked at many open-source projects and documentation is the area where most things fall apart. We have to look at the whole picture regardless of how big the application is; even if it's a demo I want to know how it works. The SourceForge projects I'm involved in are pretty weak on documentation and I try to rally the troops to properly write about what they're doing and thinking within their code. It's like trying to land a plane and asking, "What does that dial over there mean?" "Well, Jase, it doesn't say anything, apart from the fact that it's being written at the moment." We can do better; we can do better.