People often want to include screenshots when writing help pages for Ubuntu. Unfortunately, they usually don’t work well. As Usable Help’s Gordon Meyer puts it: “The overuse of screenshots is the most obvious sign of an amateur’s attempt at technical writing.”
Why are screenshots usually unhelpful?
Often they aren’t informative. Remember, the objective for help pages is to help people achieve their goals — not to advertise programs and windows. A sentence or two can usually be more helpful than a screenshot, in less space.
People often think a screenshot is the real GUI. You can watch a video [6 minutes, 48 MB Theora] of someone having this problem during a Novell usability study. That isn’t a one-off case: Apple saw it happen in their own usability studies.
Usually screenshots are too big for the help window. It’s easiest to follow instructions in a help page if the instructions, and the program you're doing stuff in, are visible on the screen at the same time. This means the help window will usually be too small to show a screenshot of an entire window, without icky scrolling.
Screenshots are harder to update and localize. A screenshot full of English text isn’t much use to someone using the GUI in a different language. And the Ubuntu translators can’t help you out by localizing screenshots, because Launchpad doesn’t support localization of graphics yet.
Let’s ban them, then!
Well, no. Screenshots can occasionally be useful, if you’re careful. Thinking about the problems above reveals some guidelines for using screenshots well.
Use them only when they’re really better than text. This is often true for graphic elements that don’t have labels. For example, if someone searches the help for “Why has an orange square appeared at the top of the screen”, they should end up at an “Updating your system” page that includes a picture of that same updates-available icon — reassuring them that you’re talking about the same thing they are.
Don’t make screenshots look like the real GUI. If you’re showing something less than an entire window, you can do this by fading out the edges of the screenshot (but don’t fade out the actual thing you’re showing). And if you’re showing a large area or an entire window, shrink it by 25% or so, so that it’s obviously an illustration.
Keep them small. Smaller images are more likely to be relevant, less likely to be confused with the real GUI, and easier to see in a small help window (not to mention easier to fit onto the Ubuntu CD).
Avoid screenshots that show text. Concentrate on using screenshots to explain graphic elements that don’t have labels.