By the time users hit the help documentation, they’re already snarly. Yeah, some people read the documentation first before using the tool, but…

A lot of people just want to dive in and start using the tool. And when I’m stuck I want answers. Now, already!  You might think it’s stupid-user error and I might think it’s stupid software design, but who cares? I want help right NOW.

Troubleshooting information lives or dies by the search-and-I-better-frickin-find-what-I’m-looking-for mentality. How do we look for this help? We copy and paste error messages into a browser and search.

When my ideas about organizing  troubleshooting information compete with how Google finds stuff, Search Engine Optimization (SEO) carries the day.  Or at least it should. Of course, there are SEO factors that put help documentation at a disadvantage, but that’s another topic for another day and I’ll let Tom Johnson do the talking on that one.

What does this mean for me, a technical writer?

Well, if two (or 5) of our tools throw the same error message, I’m going to have one page for each error message and have instructions on that page that explain how to fix it in each tool. Yeah, it’s nice to have tool-specific help information, but Google gives more weight to page titles and URLs. For good measure, I’m going to repeat the error message in the body of the page and format it in bold or italics.

Sarah Maddox highlights elements of what makes a good error message (including some hilarious examples of bad ones), so no need for repetition.

Aside from clarity, what do I want in an error message?

Firstly, I’d like to be able to copy and paste it.

Secondly, I’d like the solution to be stated.

As an added bonus, I’d like to be provided with a link in that message that would bring me to the dialog where I can take remedial action. Then, I won’t even have to look for help information. I can just fix it. Here’s an example of one these helpful messages from our Eclipse plug-in:

See? Documentation not required. The solution is outlined, and you can click the link to get to the license dialog, where you can check your host and port information.

Hmmm. Maybe that would put me out of a job. Sergey, please change that message to:

ERROR:FROZEN:BAD LICENSE.

I have a mortgage to pay here.