Re: Clarity or Talking Down?

[Bill Bledsoe <Bill -dot- Bledsoe -at- CMS-STL -dot- COM>]

Kevin,

You'll find my comments interspersed below:

Feeman Kevin SC2275 wrote:
>
>      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.

At this point, we've established that there is indeed a problem.  The
developers know that it doesn't work, but they're not paid to figure out
why... you are.  More on this in a second.

>      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 unnecessarydialog
>      2. When a command is supposed to by typed, put the word Type "xxxxx"

And these are your suggestions... not the suggestions of the developer
or the manager, but rather the suggestions you made, as a professional
tech comm who's job it is to make a lot of the "mud" you see into clean,
usable stuff.  Again... there's a point coming here...

>      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!"

Well... wait a second, wasn't this given to you?  And after the
developer's complained that there was something wrong it and that it
needed clarification?
<Whooray... here's the point!>
I think that what needs to occur here is that you need to make a case
for you being allowed to "do YOUR job" and that in your professional
opinion... the best way to document this procedure is to include the
text the user needs to enter.

This text is not superflous detail, it is part of the procedure.  If you
wanted to discuss the genesis of ClearCase in the middle of a step...
the folks at PureAtria might like it... but to your users... that's a
problem.  Bottom line, you can't be too clear to any audience, when you
have a mandate saying that what they have already isn't clear enough.

just my $02 worth...
--
****************************************************
Bill Bledsoe
Senior Technical Writer - CMS
Bill -dot- Bledsoe -at- cms-stl -dot- com or intlidox -at- anet-stl -dot- com

"I'm out on a limb where the fun begins"
              Adrian Belew/The Bears
****************************************************
If Bill Said it, Bill said it... Not CMS.  Got it?
****************************************************

 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