Knowing the Audience

Now, covering a topic like custom painting involves first describing painting in AWT, and then talking about what's changed in Swing. And as you might imagine, there are many excellent articles out there that already do this. The most relevant is Amy Fowler's discussion of painting in AWT and Swing, available at http://java.sun.com/products/jfc/tsc/articles/painting/

As a technical writer, a large part of my job here at Sun is knowing the audience and adjusting my writing style to suit. We've found that the tutorial audience responds very well to complete examples... code that you can see in its entirety, with narrative that gives the reader a specific, guided walk-through of the concepts. This approach is very different from say, writing a whitepaper for JavaOne, or making a clarification to the platform API spec. So how do I go about documenting a subject that has already been covered elsewhere? For me there are two basic steps: 1) learn the facts (AWT and Swing painting subsystems in this case) and 2) create a new presentation from scratch... one that is fresh and not just a copy of something else already out there.

In this case I thought that since custom painting is a "visual" activity, it would make sense to start with something basic (like a Frame or JFrame), then add a drawing surface (Canvas or JPanel etc.), then add some new piece of functionality in each subsequent section. This allows the reader to learn in stages as the application evolves. By the time you finish the lesson, you'll have walked through the concepts that we consider important (by "we" I mean myself AND the Swing engineering team), and hopefully when you're done, you'll think "Wow, that was easy!"

The lesson is currently up for engineering review, but will be posted to the tutorial in early July. Make sure to come back then and check it out!

-- Scott Hommel

Posted at 04:23PM Jun 05, 2007 by The Java Tutorial Team  |  Comments[4]