Explaining Java's Graphics System | Java's Poor Documentation

One of the hurdles in teaching graphics early is that Java handles graphics in a way that's hard to explain. This results in the graphics code that's handed to the student being treated as a piece of "black magic" for some time. At least with Swing being a standard part of Java now (though the observant student will wonder about that javax.swing thing) it appears more functional.

Sun's explanation makes interesting reading. If you're into doing jigsaw puzzles, this will be right up your alley. I especially like this particular comment near the beginning:

Both the AWT (abstract windowing toolkit) and Swing provide such a [graphics] framework. But the APIs that implement it are not well understood by some developers -- a problem that has led to programs not performing as well as they could.

Since this basically translates as, "Bad programs are written by programmers who can't read our minds," it's not a very flattering comment for Sun's readers.
The paper itself struggles to make sense of it all by recounting the history of Java's graphics subsystem. The reader is left feeling like they walked in on the middle of a conversation since the paper ends up taking so much for granted on the reader's part. I'm sure this was to keep the paper down to a readable length, but it'd be nice to have something both brief and clear. An experienced programmer can sort it out, it's not a hopeless paper. But it's the sort of documentation that keeps the third party market for Java books thriving.

The historical approach and starting the conversation in the middle pervades the Java API Specification as well. Seldom is a clean slate approach taken to explaining anything. Most method descriptions are direct enough, but the descriptions of the packages and classes are meaningless without plenty of background. If you haven't been using Java since 1995, then you have to act like it and go back and read the documentation for the earliest classes to have the background you need to apprehend the references made in the documentation for the new classes.

There's also no functional guide in the standard documentation. If you want to do something specific, you can spelunk around and hope that you'll turn up something. Since the verbs are in the methods within the classes, functional information is hidden below the class names presented in the API reference. Once you do find a class that seems to have the methods you're looking for, you have to hope that you've actually found the best way of doing something. The result is that the best functional guide to Java is Google.

The Java tutorials alleviate the pain to a small degree, but my experience is that most programmers find that they move too slow when the programmers want a direct answer to a question they have. They may come back to the tutorials after they've implemented some working code, to see how it jives with the information in the tutorial, but they'll seldom stick with the tutorial on the first pass.

I suppose it's too much to ask that documentation be written with the usefulness and clarity of, say, the Vic-20 programmer's guide. ;)