{"thread":{"id":"30418","subject":"Clarity of error messages","startedAt":"2012-05-04T04:20:18Z","lastAt":"2012-05-04T04:20:18Z","messageCount":1,"participants":["Sitaram Chamarty"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"190715","messageId":"CAMK1S_hYRN=Td8oOZwtMud2-NyUX=jHWMGHG5ziD8axdQPF8tw@mail.gmail.com","threadId":"30418","inReplyTo":null,"subject":"Clarity of error messages","fromName":"Sitaram Chamarty","fromEmail":"sitaramc@gmail.com","sentAt":"2012-05-04T04:20:18Z","receivedAt":"2012-05-04T04:20:18Z","isPatch":false,"sender":{"key":"sitaramc@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43316?v=4"},"body":"On Fri, May 4, 2012 at 8:43 AM, Nathan Gray <n8gray@n8gray.org> wrote:\n\n> I just led a team of reasonably bright people through a transition\n> from SVN to git.  Not one of them understood this message.  Every one\n> of them thought something was broken.  This is a very common\n> occurrence, so a short, simple message without jargon for this error\n> would be a big, big win.\n\n[Doesn't matter what error message we're talking about so I snipped\nout most of this.  Also snipped out most of the original recipients\nand changed the subject line to better reflect the specific topic that\nevolved.]\n\nWhat I have to say comes from my experience developing, documenting,\nand supporting gitolite, (a project that is far smaller than git).\n\nNo one will ever agree on human-readable text.  It's not\nbike-shedding; that's the way it is.  I have changed the gitolite\ndocumentation far more often than I have changed the code, so far.  In\nfact, I have started batching documentation changes due to the sheer\nnumber of them.\n\nAlso, some people don't want to read documentation or learn a bit\nabout the tool before hand -- they would like the error message to be\nall they need to read.  (I wonder how they learned any programming in\nthe first place!)\n\nI am starting to think that the correct treatment for error messages\nis to assign every error a number (a la IBM mainframes; S0C7 anyone?)\nand force people to look it up in one or more of the following\n\"indexes\":\n\n  - brief\n  - verbose\n  - verbose with examples\n  - technical/internals\n\nThe default could print the \"brief\" entry along with the error number.\n\nThat won't reduce the arguments about what the message should say but\nat least you can better accommodate more than one opinion.\n\nPerl folks might recognise this as something like the 'diagnostics'\npragma and/or the 'splain' program, although (1) perl does not print\nerror numbers you can look up using 'splain', and (2) perl has only\none \"index\", while I am suggesting 4 different ones.\n"}]}