Documenting GUI components that are not labelled?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Susie Pearson reports: <<The majority of the components in the GUI I'm
documenting are not labelled.>>

_Everything_ is labeled somehow, though perhaps not with words; if not, what
you're describing is a unmarked sheet of lined paper, not a user interface,
and not even the designers would be able to use it. Labels may be colors,
icons, text, or a variety of other things (lines, symbols, patterns). The
trick is to define what types of labeling you've actually got, then come up
with an efficient way of referring to it.

<<I'm taking screen caps as I go along, but when I explain what a text
field, list, etc. is for, how should I indicate to the user what GUI
component I'm using?  Callouts on the screen cap?>>

Callouts are a great solution, since nobody remembers icons. (Want proof?
Find a colleague who uses Word's toolbar instead of the menus and use the
Customize option to rearrange the icons. Sit back and wait for the screams
of frustration. <g>) One very successful trick I've used in the past is to
create a foldout flap at the back of the manual that contains all the images
that readers will repeatedly refer to. To use the docs, readers simply
folded this flap out so the images sat to the right of the manual pages, and
referred to the graphics as required while they read the main text. You can
do the same, but with a full-screen image that you repeat only once, on that
foldout page. Where something isn't labeled, give it a descriptive name or
(better still) a few words that provide a more complete description (e.g.,
"Enter your name here (don't use any numbers or symbols)", which also
includes an affordance that tells users how to enter data). Then, all you
need say is "Next, enter your name"; the large callout diagram tells them
where.

<<Should I perhaps talk to the GUI designers about labelling screen
components?>>

Unquestionably. We English speakers are a very verbal folk, and it's been
shown time and again that words are far more meaningful to most users than
icons. Icons are great shortcuts, but they rarely completely eliminate the
need for text. Want more proof? Ask Microsoft's usability labs why they
created tooltips and other popups in WinHelp: because users could never
figure out the meaning of cryptic icons unless they used the icons
frequently, and even then, they tended to remember the position as much as
they remembered the meaning of the symbol. So Microsoft had to come up with
a way of unintrusively labeling interface elements so people could figure
out what icons mean. If you can't con your developers into using real
labels, perhaps you can convince them to use tooltips.

<<I don't think the unlabelled GUI components will give users grief, it only
makes it hard for *me* to document.>>
 
Want to bet a beer that the users won't find unlabeled fields any easier to
use than you find them to document? Sucker bet... This might be an excellent
time to put together a focus group of potential customers and ask their
opinion. You could probably do this for $20 per head and a cup of coffee; I
used to earn beer money in university attending market research sessions
that paid less than this.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."-Kim Roper 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  And it's
affordable.  Join our alomst 10,000 published authors today.
http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.