A comedy of errors

I’m a sort of sophist: Give me a topic and I will argue for either side. It makes no difference to me the rights and wrongs of what I am arguing, what makes the difference is the ability to put together a coherent, even if specious, winning point of view. I think that this is one of the reasons I like technical writing so much. You have to understand what you’re writing about from so many different viewpoints, such as the technology, the marketing take on that technology (wherein creeps in the specious descriptions that form the backbone of any introduction I write), and of course how the user will use the technology. What you write must then be a coherent synthesis of these often opposing viewpoints.

I can come up with an answer for most of what is thrown my way both in life and in my chosen profession, whether it be general questions such as should videos be incorporated within documentation, for those too lazy to read (and my answer is yes), or with more specific questions such as whether fields in a dialog should have a colon or not after the label (and again I argue the yes position). Where I have a problem is when it comes to the format of error messages. I don’t mean whether the error should include some kind of numbering system so that support can respond more efficiently, along the lines of AAAnnnnm where AAA identifies the module generating the error, nnnn is the unique error ID and m is the error severity. What I mean is what should the actual text of the message include?

Error messages inform you that an error has occurred. Some let you know why the error has occurred. Very few actually help you resolve the problem. So an error message such as “An error occurred while deleting the queries” lets me know that something is wrong but is not going to win any prizes for helpfulness. The error message “An error occurred deleting queries that were still running” is more helpful assuming I can identify the queries that are still running. I can then wait for them to finish and run them again. Better still, “The queries abc, 123, xyz are running and could not be deleted” saves me the trouble of finding out for myself which are the problematic queries. So where exactly do I have a problem with error messages?

Well, it’s whether to reword the error to include the solution, or leave that for the user to figure out. So instead of “The queries abc, 123, xyz are running and could not be deleted” the error could have been worded “The queries abc, 123, xyz are running and could not be deleted. Wait for them to finish running and then delete them.” But is this really a good idea? In the simplistic case I’ve used here it is a good thing, but errors are rarely that simplistic at source, and if they are they are only a small number within the bigger set of possible errors. So if I can give a solution do I, leaving the user frustrated when I can’t, or do I word the error message so that the user can work out what to do when that is possible and just suffer in silence when that isn’t possible.

It’s really about frustration levels. Errors increase frustration, so providing the solution with the message can reduce this frustration. However, when errors require a lengthy solution, or possible multiple solutions, or options which need to be tried dependent on the current situation, or … this is just not possible, and if some errors messages include solutions, the users expectations are raised, that all error messages can have solutions stated with the error, which is mostly not the case. Is it better to raise expectations and then shatter these expectations or not raise them in the first place? I don’t have an answer.

As a technical writer, also responsible for the clarity of the error messages, I work around the problem by keeping the error message as simple and concise as possible and creating and error guide to include all the potential solutions, with a get out line like “Contact support” for the messages that have no resolution that can be included in the error guide.