From: carl@SOL1.GPS.CALTECH.EDU (Carl J Lydick)
Newsgroups: comp.os.vms
Subject: Guidelines for posting questions to comp.os.vms/info-vax
Date: 22 Nov 1992 18:57:02 GMT
Organization: HST Wide Field/Planetary Camera
Distribution: world
Reply-To: carl@SOL1.GPS.CALTECH.EDU
NNTP-Posting-Host: sol1.gps.caltech.edu

I'm proposing the following guidelines for posting questions to this group. 
One would hope that everything I mention below would be obvious to anybody
about to post a question, but that's far to seldom the case (especially in the
period from September through November).  I welcome comments and suggestions
for improving the guidelines.  Responses from Jerry, Jamie, and (shudder) Ehud
(please, Ehud:  Don't turn the temperature up TOO high) would be especially
welcome.

The following guidelines for posting  questions  to  COMP.OS.VMS/INFO-VAX  are
intended  to help querants post their questions in such fashion as to maximize
the probability that they'll receive quick, useful responses, and to  minimize
he probability that the questions will annoy the people most likely to be able
to give useful responses.

Chances are, before you'll actually get a useful response  to  your  question,
you'll have to conform to these guidelines anyway, so you might as well try to
do so in your original question instead  of  wasting  several  days  and  some
network bandwidth clarifying your question.

Perhaps the most important thing to remember is:  You've run into  a  problem,
and haven't been able to figure out how to solve it.  One possible explanation
for this is that you're going about it the wrong way.  Therefore,  asking  for
help  solving  a minor problem in what you think is a "solution" to your major
problem may do you no good whatever.  So in general, there are two things  you
ABSOLUTELY need to tell us if you want help:

1)  How we can get in touch with you to answer your question;
2)  What you are trying to accomplish;

Now, for the specific guidelines I propose:

1)  First and foremost, if you want us to e-mail  responses  to  you  (and  in
    general,  I'd recommend that you actually read this group; there really IS
    a lot of useful stuff you can pick  up  that  way),  please  include  your
    e-mail  address  (including  a fully-qualified domain name) in the body of
    your  message.   The  news/mail  gateway  mangles  addresses.    In   both
    directions (well, actually, I think it's UUNET.UU.NET that tends to mangle
    addresses coming in via mail).  If you really  need  to  have  a  response
    mailed to you, the only way you can guarantee that we'll be able to figure
    out how to do that is if you give us your e-mail address.
2)  If your question is about a VMS utility that doesn't do what  you  expect,
    include in your question:
    A)  The command you used that generated the "improper" response;
    B)  A description of what you  thought  the  system's  response  should've
        been.   A question of the form "X doesn't work properly.  How do I fix
        that?" is unanswerable.  We have to know HOW X doesn't work  properly.
        Sometimes  the  answer  will  be "X isn't supposed to do that.  You've
        misunderstood the documentation.  To get the response you want, use  Y
        instead."  But  we  can't help you unless we know what it was you were
        trying to accomplish."
    C)  The FULL error message (if any) given to you by  VMS.   VMS  is  *NOT*
        unix.   VMS  error  messages  usually  contain LOTS of information for
        those who understand them.  But we need the FULL  text  of  the  error
        message, exactly as VMS gave it to you.  Vague mention of the message,
        like "it said I didn't have enough memory" is useless.  The actual VMS
        error message, for example, in a case like this example, would usually
        have told us WHAT KIND of memory you ran out of.  So  please,  VMS  is
        trying  to help you find the problem; do us the same favor and give us
        all the information VMS gave you.
    D)  The version number  of  all  relevent  software.   Oddly  enough,  the
        version  numbers  aren't  just  time  stamps.   Things actually change
        between versions of software.  Bugs in one version might not  show  up
        in  other  versions.   So  if you have actually stumbled across a bug,
        please let us know what version of the software you're running, so  we
        can decide whether we might be able to help you.
    E)  Complete  descriptions  (output  of  ANALYZE/RMS/FDL  would   ususally
        suffice) of any of your files involved in the problem;
    F)  If it appears to be a problem with SYSGEN parameters, let us know what
        your  SYSGEN  parameters  currently  are.   Some SYSGEN parameters are
        interrelated.  Since you haven't been able  to  diagnose  the  problem
        yourself,  don't  be  too  sure  that you're even looking in the right
        place.  Again:  Give us all the information that might be necessary to
        solving  the  problem.   Don't  just give us the SYSGEN parameters you
        THINK are causing the problem.  Give us ALL the SYSGEN parameters that
        MIGHT POSSIBLY have an effect on the problem.
3)  If your problem is that some user-written code doesn't do what you expect,
    then  don't  try  translating  from C (or PASCAL, or FORTRAN, or BASIC...)
    into  English.   Believe  it  or  not,  most  of  us  who  participate  in
    COMP.OS.VMS  actually  understand  one  or more programming languages, and
    some of us even have compilers that we can use.  Furthermore, 99%  of  the
    "compiler  bugs"  people find aren't compiler bugs at all:  they're poorly
    written application code.  By the time you've converted your code into  an
    English  description, you've almost certainly glossed over whatever it was
    that was REALLY causing the problem (once again:  If you knew enough about
    the  real  problem  that  you'd  think  it important to mention it in your
    English-language description, you'd probably also know how  to  solve  the
    problem).   So  don't do us the favor of "summarizing" your problem.  When
    you do that, the problem itself usually gets summarized out of  existence.
    Instead,  find  the  code  that's  causing the problem.  If it's something
    huge, try to find a simpler version of the same sort of code that  creates
    the  same  problem.  Keep working at it until you've got a program of less
    than 100 lines of code that produces the problem, or until you can't  find
    a simpler example that demonstrates the problem.  Strangely enough, by the
    time you've done this, you'll have found the problem  yourself  more  than
    half the time.  And if you HAVEN'T done this, chances are that nobody else
    will be able to figure out what you're talking about enough to  help  with
    your problem.

    If, once you've reduced the problem to the simplest example you  can,  you
    still can't figure out what's going wrong, then post the code, the version
    number of the compiler, complete descriptions of any  of  your  own  files
    that  seem  to be related to the problem, and, as always, a description of
    what you think your code SHOULD do, to us, and  you'll  likely  receive  a
    prompt and useful answer.
--------------------------------------------------------------------------------
Carl J Lydick | INTERnet: CARL@SOL1.GPS.CALTECH.EDU | NSI/HEPnet: SOL1::CARL

Disclaimer:  Hey, I understand VAXen and VMS.  That's what I get paid for.  My
understanding of astronomy is purely at the amateur level (or below).  So
unless what I'm saying is directly related to VAX/VMS, don't hold me or my
organization responsible for it.  If it IS related to VAX/VMS, you can try to
hold me responsible for it, but my organization had nothing to do with it.