[buug] Best practices for stderr messages?

[Claude Rubinson]

I'm wondering if anybody might be familiar with a "best practices"
document for writing error messages, specifically for shell scripts
outputting to stderr.

I'm not so interested in recommendations for formatting conventions
(although that would also be welcome) but, more specifically,
recommendations for phrasing, useful/conventional terminology, etc.  I
find myself struggling to balance clarity and brevity and am wondering
if somebody might have already talked about the issue.

In Erik Raymond's /Art of Unix Programming/, he provides a list of
conventional/common flags for shell scripts.  In a sense, I'm
wondering if there might be a similar analogue for error messages.

The program in question is a collection of shell scripts that I'm
writing for social research analysis.  There will be some seasoned
Unix/Linux users in the target audience but many will be Mac or Linux
people unfamiliar with Unix conventions.  I expect that users will
have a range of familiarity with the technique from novice to expert.
So I have a particular interest in my error and warning messages being
technically precise but also straightforward and intelligible, without
being too verbose.  (One thing that I'm doing to help accomplish this
is to provide references to published and unpublished articles that
discuss the issue raised by the warning/error, e.g., (see: Rubinson
2009), which should help a bit.)

Thanks!

Claude