Collect the methods of solving an error by simplifying the filing of solutions.
A while back, I gained no traction when I blogged about unique error codes. Let me re-blog this for the few readers I have:
Consider a typical error message:
Something broken in Convert: no pipe: fail
Consider Oracle’s style:
CVT-01106: Something broken in Convert: no pipe: fail
The key difference of course is that “CVT-01106” is a code that can be sued to look up more details and solutions after the fact.
…but that’s old. It’s form the old Oracle-5 days, where you could type “oraerr ORA 01008” to find out what the error “ORA-01008” meant, and I assume if there was a “CVT” part of Oracle, you could type “oraerr CVT 01106” to get more ideas, solution suggestions etc.
I suggested while I was at Cellon / CEC Wireless that creating a simple list of sections error code — like “CVT” and “ORA” — would help to diagnose errors. Apparently I lacked sufficient Guanxi to be correct.
I suggested at Motorola and Phorm that dumping links to a Wiki would help to form user-generated resolution links (both for internal consumption, but Motorola has thousands of people, 700 alone were developing the LJ Line). That got no traction, but my little prideful inner voice is happier that those who said “what’s FLOSS? you made that abbreviation up” may realize I was clued in and reconsider those of my ideas that I *did* invent (or re-purpose, like this one)
Years later, I maintain that if you want to avoid having to google for results and sift through bad search results, you want to make it really easy to find details about the error — just like Oracle used to. Further, if that content is updated, people will see the value of the resource. Finally, if that content accepts user-input, they may suggest alternative fixes.
The way to make it really easy to collect error results is still Wikis and Tags.
In order to leverage Wikis, you need to include a unique code in your error-display routines that displays a permalink to a wiki server. The pages for those errors need not exist — support issues can include adding descriptions to wiki pages if necessary, and users can submit possible fixes themselves. Although these might need an audit loop until a user has enough Guanxi (influence, trust) to (gasp!) post solutions without a auditor/babysitter, this distributes the workload of adding content.
As a single repository, this collection of information relative to your product will only grow so long as it’s available and the reference URL is reinforced by being consistently provided for all errors. A usable resource will get additional references from external sources, effectively driving eyeballs to your resource rather than to a thousand different mailing lists, blogs, etc scattered across the web.
Lacking this, use Tags.
A Consistent tag with unique parts becomes an easy searchable term. Including this tag in every similar error message causes those discussions to become searchable with a better accuracy. Consider the following:
BoxKicker: BXXa4139176a : I think I am broken
The error message means almost nothing, but the string “BXXa4139176a” — as a unique string — won’t get parsed into two parts (as it would of the “a” separators were hyphens) and whenever users talk about the error, they’ll probably cut-n-past that code. The solution to the problem may be found soon after, or at least an intelligent conversation.
The result is that although you’re not collecting and controlling/auditing the solution comments, you do make the user-provided ocntent scattered across the ‘web easier to find, with more successful searches than otherwise. Blog feed may also use this code since it seems unique. Tags in tools such as Del.icio.us have a strong chance to use these codes. From the tag-aware to the blissfully-ignorant, the chance of finding solutions to your software increases.
… all with very minimal effort. A good piece of auto-increment sourcecode can manage these codes for you.
Such a benefit for such a low cost, why wouldn’t you do it?
