Document our conventions for writing messages

[imply-cheddar]

This adds some documentation for our message-writing conventions.

[abhishekagarwal87]

LGTM.

[gianm]

Looks good to me as-is. Had a couple of questions that don't block my approval. Thanks for starting this off!

[imply-cheddar]

@paul-rogers @gianm both of you left comments that I have addressed with updates to the text. Just pinging to give you a chance to double check the adjustments and leave more comments if you do not feel like the new explanations make sense.

The thing I'm mostly wondering about is the explanation about [] and it not being the equivalent of quotes.

[paul-rogers]

@imply-cheddar, error messages are for end users. Even when they are for sys admins or devs, they go to end users first. As an end user of many products, I find column[foo] to be odd and un-English like. There may well be a good technical reason, but since our audience is end users, and they don't know that technical goal, we should use normally accepted English practice. That should include quotes, but if we choose to use brackets in place of quotes, at least use common spacing.

That said, the code works fine without spaces and users can get used to Druid style. So, LGTM.