On Tue, 5 Jun 2007 15:02:06 +0200, Chris Mason wrote:
>
>Try to find out which development lab is responsible for the product - if
>you don't already know - and write a letter to the lab director - as if I
>needed to tell you - indicating how ridiculous this response was.
>
Well, I chose to defer the skip-level and to appeal to the tech writer
to (appeal to the developer to) reconsider:
I was extremely disappointed by that, focusing on the
sentence:
... I probably would not say anything about the
syntax rules that are followed because you may
give misleading information.
It is the responsibility of a Command Reference to provide
a correct specification of the command syntax so that
programmers don't develop their own "misleading information".
Please go back to the developer; ask him to consult the
design document if necessary, and to determine what the
intended syntax of the command is and to produce suitable
input for the next edition of the Command Reference. If
necessary, take the draft to your test group to validate
that the product actually conforms to the specification.
OK. Perhaps I'm being unrealistic. I suspect this product
was developed under extreme time pressure. The developer
may have been given considerable freedom: "Use your judgment;
make it work." It's now time to discover the decisions the
developer made and provide the documentation for the customer.
Ask the programmer what choices he made if he's available;
read the source code if necessary. Document the syntax.
<specifics snipped>
I didn't even say "ridiculous". I'll leave it to the tech
writer to infer that.
-- gil
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to [EMAIL PROTECTED] with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html
