Re: Cooperative Programmers: (Was: Documents Before Products)

[Sheila Govindaraj <sheila -at- ADITI -dot- COM>]

Yeah. This is something akin to what happens in my organisation. If I am
not very comfortable with the UI or if I find that there's a certain
level of discomfort with the procedure I'm documenting, I normally walk
across to the Dev guys and talk to them. They are most cooperative and
are always ready to give that extra inch to make their s/w friendlier.
But the hitch is I'm always asked to report the point I've raised as a
bug, which I hesitate to do. A bug is a bug only if the product does not
conform to the specs (at least where I'm currently working <g>).

So I have a suspicion that the dev guys try to get back at the Program
Mgmt team (who write the specs) through me. I don't mind this though, as
long as the product improves. I take the easy way out and send a mail on
the points I've raised to just about every body who is somebody in
Product Development. My point gets across and Program Mgmt includes my
comments in the specs! Quite a roundabout, eh? I've been forced to adopt
this measure, if you like, 'coz if I comment on any possible improvement
to Program Management (I report to the Program Manager), she takes the
credit for it!

And a note to Gurudutt from India: there's a whole bunch of Tech Writers
and Online doc developers (35 to 40 of us!) here in Bangalore, India.
We've got a hotline going (via email). I remember emailing you a couple
of months ago, but you did not respond!
Hey listers! PLEASE DO NOT FLAME ME FOR THIS.

Sheila Govindaraj
sheila -at- aditi -dot- com
Aditi Technologies India
http://www.aditi.com

>----------
>From:  Brett Peruzzi[SMTP:Brett -dot- Peruzzi -at- FDC-INVEST -dot- COM]
>    A few times in my career when I have asked programmers to verify
>that
>     software worked the way I had described it, their responses have
>     floored me.
>
>     Both of these individuals were so cooperative that they offered to
>     rewrite their code to comply with the documentation when it didn't
>     match the program's functionality. One even said, "How do you want
>it
>     to work?"
>
>     I suspect that they weren't clear on how the software should
>function,
>     due to fuzzy or non-existent specs, and were using my doc as a
>     specification.
>
>     BTW, in both cases I told the programmers that my primary job was
>to
>     document the program, not determine how it should work. But if I
>felt
>     I could contribute to the usability or interface design, I gave my
>     opinion.
>
>     Anybody else encountered this situation?
>
>     Brett Peruzzi
>     First Data Investor Services Group
>     Boston, MA
>     Brett -dot- Peruzzi -at- fdc-invest -dot- com
>
>
>
>
>At 10:42 PM 3/13/97 +0530, Guru wrote:
>
>>In one product for which I wrote a user manual for an Indian Company in
>>America, I did the same technique.  One particular function was
>>simultaneously being developed and documented.  Poor me did not understand
>>what the programmer had said.  I wrote with a little bit of imagination.
>>To my surprise the director talked to me a few days later and said that
>>they had decided to follow the user interface which I had described.
>
>I once joined a company shortly after the release of a major hardware
>system. Because we were short of space, I shared an office with two
>other
>writers and witnessed a meeting with some diagnostic programmers. It
>seems
>that one of the writers couldn't get information about how certain
>diagnostics were going to be implemented. Knowing that there wasn't
>enough
>memory in the diagnostic processor for this particular diagnostic to
>run, he
>speculated that the only way to accomplish these tests was through
>DEBUG. He
>wrote it that way, and the manual breezed through review cycles with no
>comment. In the meeting I witnessed, the diagnostic programmers were
>consulting with the writer so that their code would conform to what he
>had
>written in the released manual.
>
>--Wayne Douglass
>
>
>

 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