TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Thinking outside the typographic box! From:geoff-h -at- MTL -dot- FERIC -dot- CA Date:Tue, 16 Dec 1997 08:54:06 -0600
Melissa Fisher made the important point that sometimes the
correct solution depends on what the audience expects. For
example, in a command reference, she <<I tried going the
"plain text" route, but it was hard to tell when the name
of a field or option ended and the rest of the sentence
began. Without laboriously (and often clumsily) writing
around all these labels, we chose to use bold face only for
options/field names on a dialog.>>
That's the traditional approach, and it certainly works.
I'm just not sure it's the best approach. Donning my
devil's advocate cap = -at- 8^{)} I pose the following question
to lead us to <cliche> think outside the box </cliche> of
tradition: how could we do it better? Let's toss a few
cats among the pigeons: How about a flow chart? How about
an iterative example ("to solve all your problems, type:
fubar /all", "to solve all your problems and feel much
better, type: fubar /curse")? How about a table approach?
Command Mandatory switches Options (choose as many
(choose only one) as you want)
------- ------------------ ----------------------
fubar /all /curse
/some /pray
/invoke_the_name_Gates
<<For the text screens, we did choose to use a different
font, and chose one that closely matched the actual font
used on the screen... we felt that by trying to match the
text to the screen was the best way to eliminate as much
confusion as possible.>>
Excellent choice. There's no point adding barriers to
comprehension by making readers visually translate between
fonts. Screenshots might have worked even better, depending
on the context, since they provide not only correct
typographic cues, but also positional relationships that
may be important.
--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: Speaking for myself, not FERIC.
