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: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
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
