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.
Scott Parsons reports: <<My co-workers are minimalist procedure writers and
I'm a low-level procedure writer. That is, I write "On the File menu, click
Open" while they write "open the record." I am currently weighing the better
method of writing>>
Neither is inherently better; they just make different assumptions. What
you're calling the minimalist approach is arguably more reductionist, and it
assumes that readers already know the basics of your software. This is a
safe assumption if you have good knowledge of your audience (which you
stated you don't) and can demonstrate that they already know these basic
concepts. It's also a reasonable assumption if you've created a short "what
you need to know to run this software" tutorial that covers such topics as
opening files.
Your approach assumes that some users need basic instruction, and that's
more broadly defensible if you're not familiar with the audience. The term
"lowest common denominator" has acquired an unnecessarily pejorative
connotation, and it's worth fighting that by recognizing the power of this
approach: it meets everyone's needs. Although I have some sympathy for the
approach advocated by your colleagues, it guarantees that unsophisticated
readers in your audience will be unable to complete some tasks. You might
also want to point out some of the logical problems with the approach: ask
them why they feel a need to say "open the record" at all, since experienced
users should feel insulted at being told to do such an obvious step. <g>
Fortunately, there's at least one compromise that should meet the needs of
most users. First, as suggested above, you could create a simple tutorial
that covers the basics of opening, closing, and saving files. (Do this for
each recurring type of instruction.) If you do talk about saving data,
include some information about where the bodies are hidden and how to do
backups. Have a look at my article on the topic for some tips:
Hart, G. 2001. "Backing up" doesn't mean retreating.
www.raycomm.com/techwhirl/backups.html
Henceforth, you no longer need to describe opening files, and can simply
write "open the record". Second, use headings appropriately, so that each
major step ("open the record") forms a heading, perhaps boldfaced, and the
nitty gritty details are indented or otherwise enumerated beneath the
heading; this way, experts just skim through the headings and ignore the
details (which they already know), whereas neophytes actually read the
details. Both groups go away happy.
A third approach might be to use tables for procedures. Instead of using
headings, place the high-level info. ("open the file") in the first column,
and the detailed steps in the second column. This achieves the same goal as
the heading/procedural text separation by facilitating skimming without
compromising usability for anyone. Moreover, if you wanted to try
collaborative writing, you could ask your colleagues to write the high-level
info. and leave you to fill in the details. _You_ might end up doing more
work, but at least each group will be satisfied with the results.
<<I've read through the archive, and some say that this decision is best
made when you know your target audience. Since this is unlikely, I've
assumed our target audience is a general user. Somewhat familiar with our
system, yet new to whatever concept or procedure I am writing.>>
This sounds like a good opportunity to actually begin getting to know your
audience. You can often find out what they're thinking by joining an online
discussion group and listening in (e.g., eHelp should monitor techwr-l to
find out what we think of RoboHelp); don't think of this as spying, since
you're actually doing it to figure out better ways to help them use the
product. (If no such community exists, why not start one up? They're a great
way to keep your fingers on the pulse of your user community.) Your
technical support staff, trainers, sales staff, and marketeers can often
provide valuable information on audience. Talk to them too!
--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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002. www.ehelp.com/techwr
---
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.
