Cooperative Programmers: (Was: Documents Before Products)

[Brett Peruzzi <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



______________________________ Reply Separator _________________________________
Subject: Re: Documents Before Products
Author:  "Wayne J. Douglass" <wayned -at- VERITY -dot- COM> at Internet
Date:    3/13/97 9:43 AM


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

=========================================================
Verity, Inc.                 Email: wayned -at- verity -dot- com
894 Ross Drive           Telephone: 408-542-2139
Sunnyvale, CA 94089      Facsimile: 408-542-2040
Connecting People with Information: http://www.verity.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

 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