Clarity of error messages

On Fri, May 4, 2012 at 8:43 AM, Nathan Gray [off-list ref] wrote:

I just led a team of reasonably bright people through a transition
from SVN to git.  Not one of them understood this message.  Every one
of them thought something was broken.  This is a very common
occurrence, so a short, simple message without jargon for this error
would be a big, big win.

[Doesn't matter what error message we're talking about so I snipped
out most of this.  Also snipped out most of the original recipients
and changed the subject line to better reflect the specific topic that
evolved.]

What I have to say comes from my experience developing, documenting,
and supporting gitolite, (a project that is far smaller than git).

No one will ever agree on human-readable text.  It's not
bike-shedding; that's the way it is.  I have changed the gitolite
documentation far more often than I have changed the code, so far.  In
fact, I have started batching documentation changes due to the sheer
number of them.

Also, some people don't want to read documentation or learn a bit
about the tool before hand -- they would like the error message to be
all they need to read.  (I wonder how they learned any programming in
the first place!)

I am starting to think that the correct treatment for error messages
is to assign every error a number (a la IBM mainframes; S0C7 anyone?)
and force people to look it up in one or more of the following
"indexes":

  - brief
  - verbose
  - verbose with examples
  - technical/internals

The default could print the "brief" entry along with the error number.

That won't reduce the arguments about what the message should say but
at least you can better accommodate more than one opinion.

Perl folks might recognise this as something like the 'diagnostics'
pragma and/or the 'splain' program, although (1) perl does not print
error numbers you can look up using 'splain', and (2) perl has only
one "index", while I am suggesting 4 different ones.