Clarity or Talking Down?

Subject: Clarity or Talking Down?
From: Feeman Kevin SC2275 <Feeman_Kevin_SC2275_at_SATCOM23 -at- SATGATE -dot- SAT -dot- MOT -dot- COM>
Date: Wed, 28 May 1997 08:08:55 MST

Hi all,

I have a topic for discussion. I am working with a group of
software developers who were given a procedure, written by another
developer, to follow on how to start ClearCase, a software
development/build/file management tool. The developers complained
that the procedure didn't work. So, the procedure was given to me, a
person with very little programming/software development experience,
to perform. After asking a few question, I was finally able to
stumble through it. I had many ideas on how to improve the procedure,
for clarity, etc. My manager came in while I was running the
procedure and started listening to my suggestions on how to make it
easier for the developers. Two of my main suggestions were:

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?

Any advice that is given is appreciated, sent to me privately or it
can be posted directly. Thanks in advance.

Kevin Feeman
Technical Communicator
Envision, Mesa AZ Branch
home email: kevinf -at- primenet -dot- com
work email: Feeman_Kevin_SC2275_at_SATCOM23 -at- SATGATE -dot- SAT -dot- MOT -dot- COM

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: Graphics
Next by Author: Re[2]: What's a good title for a tw?
Previous by Thread: Re: Clarity or Talking Down?
Next by Thread: Re: Clarity or Talking Down?

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

Sponsored Ads