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: Clarity or Talking Down? From:Tim Altom <taltom -at- IQUEST -dot- NET> Date:Wed, 28 May 1997 11:03:09 -0500
At 08:08 AM 5/28/97 MST, you wrote:
>
> 1. Tighten the wording in each step, stripping out unnecessary dialog
> 2. When a command is supposed to by typed, put the word Type "xxxxx"
>
> To make a long story longer, she made the comment that we did not
> have to put the clarity in Step 2 that I suggested. She goes on to
> say that if the developer's need to be told that, then "We hired the
> wrong person!"
>
> What do you all think? From my experience, sometimes (and this is
> not a flame to all developers) that developers need specific
> instructions laid out to the letter. I don't think that it is
> necessarily that the developers need all the information, but isn't it
> better to give too much than not enough?
>
Kevin, it beats me why some people want to _leave out_ steps! You can always
ignore them, but it's hellish trying to interpolate to find them! It's as
though the doc should act as a personnel capability filter. "If you have to
ask, you shouldn't be working here. Hit the bricks." It's a bizarre argument
to maintain that because a reader is educated in a discipline, they
shouldn't be given clarity. In other words, as you get more knowledge, you
should be able to make do with fewer and fewer instructions. A Ph.D. should
need no more than a two-word hint then, eh?
I'm with you. The penalty for an extra few lines isn't large compared with
the immense and cumulative lost time from developers who've been saddled
with steps they can't follow. That defeats our most basic reason for being.
I'm no fan of step explanations, but I believe firmly in task breakdowns to
a fine granularity. "Type XXX" is a fine example of such a breakdown. Good job.
Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support ForeHelp support
FrameMaker-to-HTML Conversions
HTML Help Consulting and Production
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
