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:Re: FONT STANDARDS From:"Michael West" <mbwest -at- bigpond -dot- com> To:techwr-l Date:Mon, 16 Feb 2004 13:46:45 +1100
Isaac Rabinovitch wrote:
> Michael West wrote:
>> Isaac Rabinovitch wrote:
>>> There really needs to be some careful thinking done here, and no
>>> just in the font. I wish writers and editors would invent concise
>>> ways of conveying this stuff. I hate reading "Choose X in the Y
>>> menu, then choose Z". It's hard to follow.
>> Could you perhaps expand on that comment? I'm interested,
>> but not at all sure I understand what you're getting at.
> Reasonable question.
> OK, suppose you're writing about Microsoft Word
> options. So you write about creating a backup copy. You write "From
> the 'Tools' menu, choose "Options". This brings up the options dialog
> box. Click on the 'Save' tab, and make sure that 'Always Create
> Backup Copy' is selected."
> Then you have to write about embedding fonts. You write ""From the
> 'Tools' menu, choose "Options". This brings up the options dialog
> box. Click on the 'Save' tab, and make sure that ..."
> After you've done this 3 or 4 times, your reader is screaming, "I get
> it, I GET IT.
You are assuming that you are writing material that
is designed to be "read" sequentially like a narrative.
Not many tech writers do this sort of writing. Most
of us write (most of the time) "look-up" material that
is designed to answer the user's need for information about
accomplishing *one* single task.
In a typical well-designed user guide or help system,
for example, there will be summaries and overviews
where a user can read generalized descriptions of
common procedures. This corresponds, I think, to
your "conceptual" content, and I agree that it
should be provided for those who will take the time
to work through it. But not many users *will*.
There will *also* be (and these will make up the
bulk of the guide or help system) modularized,
task-based sets of instructions for accomplishing
specific tasks. Each instruction set is self-contained,
so your user doesn't have to go hyperlinking all over the
place to find out how to do a particular thing.
By providing *both* kinds of information, you are
catering for different kinds of learners, and that's a
Your comments about using shortcuts in instructions
are generally right, but we need to be careful. I often
use shortcuts ("File>Print") in lists of procedures such as
I might design for a Quick Reference. This is material that
will be used by intermediate-to-advanced users. But somewhere
in my guide or help system, a user who wants a plain-English
set of instructions for achieving a certain end, will find it.
And, using your own example, it will look something like this:
To Automatically Save a Backup Copy of your Documents
1. From the 'Tools' menu, choose 'Options', and then click
the 'Save' tab.
2. In the list of Save options, make sure that 'Always Create
Backup Copy' is selected.
Now tell me honestly -- is that excessive verbiage?