Using screenshots in help pages
People writing help pages for Ubuntu often want to include screenshots. Screenshots can be very useful for printed manuals, but usually they're not so good for help pages. As Usable Help’s [http://g2meyer.com/usablehelp/singles/263.html Gordon Meyer puts it]: “The overuse of screenshots is the most obvious sign of an amateur’s attempt at technical writing.”
Why are they usually unhelpful?
Often screenshots aren’t informative. Remember, the objective is to help people achieve their goals, not to advertise programs and windows. A sentence or two of text can usually be more helpful, in less space.
People often think a screenshot is the real GUI. You can [http://betterdesktop.org/wiki/video/changedesktopbackground/Subject10.ogg watch a video] [6 minutes, 48 MB Theora] of someone having this problem in Novell Linux Desktop. That isn’t a one-off case: [http://urlx.org/184.108.40.206/6f157 Apple also saw it happen] in their 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 localize. Whenever a GUI includes text that changes with the locale, any screenshot in the help should match it. This is very difficult to do for Ubuntu, especially since [http://launchpad.net/bugs/102732 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 usually applies to 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”, it would make sense for them to find a picture of that updates-available icon in the relevant help page, reassuring them that you’re talking about the same thing they are.
Don’t make them 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, easier to see in a small help window, and easier to fit onto the Ubuntu CD.
Avoid screenshots that show text. Concentrate on using them to explain graphic elements that don’t have labels.
[http://bugzilla.gnome.org/show_bug.cgi?id=348495 Gnome bug #348495: Include guidelines on minimizing confusion of screenshots in online help]