On Fri, May 4, 2012 at 8:43 AM, Nathan Gray <n8gray@xxxxxxxxxx> 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html