Eliminating Confusion

In my spare time I've been doing a remodeling project in the basement of my house. I'm not very experienced with power tools and such, so for my DIY projects, I rely on documentation and tutorials that I find online. Here is one such article, about replacing a standard light fixture with one that is flush-mount. Before reading this article, I had very little knowledge of how such a fixture was held in place. But after I read it, there is no way I could *not* understand it. Take a quick look at that article and you'll see what I mean.

Being a technical writer, I found myself asking a few questions (not related to lighting) as I read this. Questions such as: "How/why is this article so effective?" and "Could such presentation techniques apply to what we document here in the Swing tutorial?" If you skimmed (or read) that article, you would see that the discussion is divided into sequential steps, to be performed in an exact order. Each step has a screenshot. Explanatory text tells just enough to describe what is needed, but does not go overboard (it focuses on changing the fixture, not teaching everything there is to know about electricity in general first!)

My current assignment is to re-write the custom painting lesson of the Swing tutorial. As it so happens, I'm trying a similar approach to the above: create an application that illustrates the various painting concepts, break its construction down into sequential steps, provide screenshots for each step, and narrate as needed. The whole point is to give you, the reader, a guided walkthrough that eliminates confusion as much as possible. I really like tutorials with a "Step 1, Step 2, Step 3" kind of approach. How about you? What kind of narrative do you prefer in a tutorial? What is it about the presentation of our own tutorial that you find effective, and what kinds of things would you like to see changed? If you've ever read a programming tutorial and found yourself still confused by the end, what is it about that presentation style that made it *ineffective*? There is no right or wrong answer here, I'm just opening this up to discussion. Maybe certain trends will become evident through your feedback.

-- Scott Hommel

Posted at 02:01PM Jun 25, 2007 by The Java Tutorial Team  |  Comments[6]