RE: Software Manuals

["Chinell, David F (GE Indust, Security)" <David -dot- Chinell -at- GE -dot- com>]

Here's a snippet I swiped from Michael West on gratuitous screen shots.
-- Bear


========================
REASONS FOR SCREEN SHOTS
========================

Whenever a tech writer asks me for advice about "describing screens", I
ask WHY they think it necessary or desirable to "describe screens". I
even do it when they don't ask for advice (hee-hee).

Since most end-user documentation exists NOT to "describe screens" but
to give the user instructions for getting work done, a little rational
analysis may reveal that most of your screen shots are unnecessary.

In much of the bad user documentation that I have had to throw away
and/or rewrite, gratuitous screen shots had been used as a no-brainer
substitute for the hard work of writing usable instructions. I think
this may be for one or more of the following reasons:

1) Programmers like to see screen shots. Who knows, maybe they take them
home and show them to Mom.

2) Junior tech-writers find it an easy way to fill up pages while
offering visible proof to their employer (usually a former programmer)
that they've actually worked out how to install and run the application.

Take your pick. But we're not working to coddle programmers' egos. Our
job (usually) is to tell users how to get their work done. Showing them
pictures of things they can already see is just blowing smoke, and they
know it, even if our employers don't. (Mine do, because I've explained
it to them. Sorry.)

I tell Help authors and user-guide writers to use screen shots only when
they have a specific instructional purpose in mind--a purpose that is
clearly stated in the caption or lead-in. One of following purposes, for
example.

1. To point out the location of something.

In complex and poorly-designed systems (especially of the non-GUI
persuasion) it is sometimes desirable to point to the location of a
particular field because it takes too many words to point to it
textually. A full-screen capture is rarely optimal for this purpose. A
small portion of the screen, with one vertical and one horizontal window
border partially showing, is enough for the user to identify the visual
coordinates of the subject area.

Sometimes even a simple line-drawing rather than a screen capture will
work best.

2. To show a comparison between two things.

Sometimes you can make an instruction clearer by showing two similar
things (command strings, for example) and pointing to the significant
difference between them. A full-screen is rarely optimal for this
purpose.

3. To show a sequence of actions or events.

Sometimes you can make an instruction clearer by showing a 'before &
after' comparison between two screens or dialogs. This is handy when a
user performs an action in one location and then views the effect of the
action in another location. A full-screen capture is rarely optimal for
this purpose.

4. To point to an area where something important happens.

In high-level and introductory topics, it is often helpful to show a
complex window -- for example a main application window -- with callouts
pointing to its most significant features and areas of activity.

Note that in three of four cases, it is desirable to show only a
particular area or object--not a whole "screen". In ALL cases, the focus
is on particular objects, not on the whole "screen".

While I can't think of many good reasons for reproducing whole
"screens", I CAN think of plenty of reasons why is a bad idea.

Think of it this way. The user hasn't come to the Help or the user guide
to find out what a screen "looks like."  No, the user is there because
he or she wants to know HOW TO DO SOMETHING. So the real challenge for
tech-writers and Help authors is coming up with an information design
that gives a quick, clear, uncluttered answer to that specific question
that the user has in mind. This is too hard for beginners, so what they
give you instead is page after page of dumb screen shots.

-- Michael West 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.