To whom should error messages be written?

[markd at macports.org]

>>> I think we should write error messages to the end user, not the
>>> portfile developer. I think we should also have a new page in the
>>> wiki called ErrorMessages, where we can list the error messages that
>>> MacPorts might print along with explanations of what the portfile
>>> author should do about them. We would describe mtree violations and
>>> ineffectual reinplaces and checksum failures (the checksum failure
>>> discussion would move to this new page from the FAQ).
>>>
>>> Or we could put all these in the FAQ page, maybe in a new section for
>>> error messages.
>>
>> I think this might not be sustainable and might lead to always out-
>> of-date
>> docs.  I wouldn't be in favor of this unless the error messages were
>> sourced out of the code itself, rather than written independently.
>
>Can you suggest an alternative?
>
>There is a vast amount of information, for example, that we want to
>impart to people who encounter a checksum error. The port command
>does not provide any of it. Instead the user must read the FAQ to
>figure out which of several reasons for the checksum error exist and
>how to resolve it. And we have some information which is for MacPorts
>users and other information which is for port maintainers.
>
>Not all errors need that much explanation, but I'm sure at least a
>paragraph could be written about each. Would you rather the port
>command print all of that out? And what if the instructions are
>inaccurate or unclear? Then we need to do a whole new MacPorts
>release just to fix it. And we know how infrequent MacPorts releases
>have been lately.
>
>I would much prefer that MacPorts itself print very little
>information to the user: only a brief statement about what happened,
>and a link to the FAQ entry about that error. Since this link would
>point to a wiki page, inaccuracies could be very quickly corrected by
>anyone.
>
>
>Just like we're talking about having a chunked guide now instead of
>the entire guide all on one page, maybe we should have one error
>message per page too instead of all on one. We could have a wiki
>template for error messages, like we have a wiki template for how-to's.

This might all be fine.  At the time I read it I was envisioning a lot of
duplication; large companies sometimes have extensive error message lists
in formal documentation.  I've thought of links to online docs in error
messages too.

I do favor error messages communicating as much information as possible in
a terse fashion though.  If they are innaccuarate or unclear I suspect it
will cause problems even for the developers at some point.  So I think any
new error message approaches to enhancing the user experience are fine,
but I'm just saying we should be careful about trying to solve current
problems that originate from error message innaccuracy or release
frequency that way.

Mark