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.
Poll: How do you differentiate commands, etc. in text?
Subject:Poll: How do you differentiate commands, etc. in text? From:Geoff Hart <ghart -at- videotron -dot- ca> To:TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Diana Ost <Diana -dot- Ost -at- msmcorp -dot- com> Date:Wed, 28 Jun 2006 15:41:40 -0400
Diana Ost wondered: <<In my current situation, we are using InfoMapping
for all documentation, which I am in the process of working over for
online use. I am removing the underlines and quotes around terms, key
names, window names, commands, etc., for a couple of reasons: it's just
too much visual noise in the documents, and because using font changes
is probably more effective than the old-fashioned typewriter style
text.>>
Sounds like a good plan. That's particularly true for underlines, since
they're the standard visual identifier for a hyperlink, and you
shouldn't use the same visual cue to mean two different things. If
you're thinking of using XML at some point in the future, it may even
be worthwhile developing tags such as <button name> and <window name>
to identify these interface features. Then you can format them all,
instantly and on the fly, simply by defining the appropriate style
sheet.
<<I have seen many different ways to handle this (from different fonts
like bold and italic, to icons embedded in the paragraph, to nothing at
all.).>>
That's because there's no unequivocal "best practice". Many options
work equally well; there may be "statistically significant"
differences, but I haven't yet seen any evidence that there are
_practically significant_ (i.e., meaningful) differences.
Note, however, that inline icons are the best choice if the thing
you're referring to is primarily graphical. A button or icon that is
entirely textual probably doesn't benefit much from being presented as
a graphical icon, but doing is is more visually consistent if most
other buttons are graphical. A graphic is always better than a verbal
description if the icon is graphical.
<<I prefer to keep things simple, but still want to make some terms
stand out (and am somewhat opposed to italics for online use--too hard
to read). We also do a lot of policies and procedures, so instructions
are for more than just software use. >>
Italics shouldn't be a problem, particularly for short bits of text, if
you're using an appropriate font. On the whole, it's become a standard
in printed material because it achieves the right balance between
effectiveness (communicating a difference with the surrounding text)
and obtrusiveness (enough to notice but not so much that it distracts).
<<What do each of you do (if anything) to emphasis text for online
use?>>
I use words combined with quotation marks where necessary. For example:
Open the Menu menu and click the Button button. Then enter your name in
the "Name" field.
The quotes aren't strictly necessary, but I find that in the work I was
doing when I came up with this approach, there were enough situations
where some form of additional emphasis was required that it was a
helpful and relatively nonintrusive way to provide that emphasis. This
may have been largely because many of the buttons and field names were
multiple words, and did not use title caps in the interface; the lack
of such emphasis (capitalization where none would ordinarily appear in
a sentence) led to enough potential misreadings that I felt the quotes
were necessary for emphasis. Using them everywhere, even where they
might not have been necessary, was consistent.
<<So far, I am doing something like this for procedures: 1. Click this
(bold) and the Blah (bold) window appears.>>
I'm skeptical about boldface because with enough commands, the printed
page starts to look like your pen was blobbing ink, and the help topic
looks like the monitor is misbehaving. You'll often see typographers
refer to this as "the ransom note syndrome" because the text looks
pasted together. The bold stands out enough that it attracts too much
attention, and that's rarely a good thing. Italics has been a
traditional solution in print because it stands out less, but does
differ enough from its surroundings that it achieves the goal of
emphasis.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
