Re: Clarity or Talking Down?

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
Search the archives at or search and
browse the archives at

Previous by Author: Re: Question: Significant digits?
Next by Author: Re: desparately seeking java-based help
Previous by Thread: Clarity or Talking Down?
Next by Thread: Re: Clarity or Talking Down?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads