Include a link to relevant documentation in error message?

Question

We create a commercial library and code examples that are being used by external developers. We have (closed, available to registered users) documentation that extensively explains how to use the library.

Many of the developers are first-time users, so a lot of rudimentary errors are encountered.

Is it appropriate to include links to the documentation in the error log? What are the possible downsides? I can foresee a few, but it seems possible to overcome the following

• Documentation URL out of date
• Version specific errors that are not reflected in the latest documentation
• Something else is wrong, and we're wasting the developer's time by sending him to an irrelevant document

Below an example of what I mean, is it a good idea to add the bolded text?

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-archetype-plugin:1.2.3:generate (default-cli) on project standalone-pom: The desired archetype does not exist (com.example.library.archetypes:library-archetype-blank:1.2.3.0) -> Please see http://example.com/docs/setting-up-an-archetype for more information and possible troubleshooting

Answer 1

According to these error message guidelines, and my experience, people like to save time by not reading documentation or help. Googling an error may be beyond them as well, so do include a link when they have a reason to click it.

Finally, you probably already know Nielsen's First Law of Computer Documentation: people don't read it. This finding is even stronger for websites, where users truly shy away from any reading that is not essential to their task. Click on Help? Never.

Users read system documentation only when they are in trouble (that's the Second Law). They are particularly attentive when they want to recover from an error. Given this, you can use error messages as an educational resource to impart a small amount of knowledge to users. Of course, error messages should be brief and to the point, as should all Web content. However, error messages can still teach users a bit about how the system works and give them information they need to use it better. To further that end, the Web's underlying technology makes another guideline possible:

Hypertext links can be used to connect a concise error message to a page with additional background material or an explanation of the problem. (Don't overdo this, though.)

Answer 2

Yes most definitively BUT :

• Link rot is going to be an issue, Ideally generate the link dynamically from a known target document but get the prefix from some form of configuration. Should the server change then you can keep older code valid by updating this config element. You can also make the doc locally available also just by changing this prefix config.
• Versioning : In the same spirit, if you can do include versioning in the link in some capacity so that the link always points to the correct version of the documentation.
• Make the doc editable Something like a wiki type site for your documentation where you can dynamically correct mistakes, ideally also allow users to comment directly on the page. this will make it much easier for your users to participate and find what they need and you will get golden information to keep your doc in good working condition but make sure you monitor it regularly and most of all participate actively yourselves.
• Generated templates have your build system generate the basic template for the documentation from annotations in the code directly. Keep it simple though, but this will ensure that every links always points to a valid documentation. If you do use a wiki make sure you can push these templates easily, and make sure you can promote the documentation site the same way you do for your code (have a dev site which is different from the prod site and promoting code to prod will perform the inserts in the prod site automatically).

If you develop with Java or .NET the doc could be included in a jar file or a DLL file and by changing the prefix your code could fetch it locally instead.

If you do choose the wiki approach I warmly recommend DokuWiki for it's simplicity and for the fact it is based on flat text files which would make it very friendly to automated injection from the build system. That said, I do not know enough about your environment or customers to really know if this would be a good fit YMMV.

Some of the most successful tools I've created took a similar approach where the error message was targeted to the actual user that would most likely perform the task. That meant that I had to do a LOT of exception catching and wrapping to make sure the error is at the appropriate level of abstraction. I also made sure that each error message would include the most likely sources of errors and points to potential solutions "Did you forget to set xxxx config value ?", "Make sure xxx and yyy do not conflict by giving them different names" etc. Where XXX and whatnot would be generated from the context where the error occurred.

This approach was somewhat simpler but also more limited. It however had the up-side that the documentation would always be present when needed no link rot possible.

Your approach is the next evolution. Much more complex but also has much more potential returns. It will be costly though but if done right will easily pay off for itself.

Answer 3

You should favor pointing to offline documentation bundled with the library, rather than online.

(com.example.library.archetypes:library-archetype-blank:1.2.3.0) -> Please see /usr/share/myprog-3.8.1/docs/setting-up-an-archetype for more information and possible troubleshooting

(obviously if it's a Windows library, the path would be different).

The benefits here are:

• This way the documentation is always in-sync with library. People develop with and troubleshoot old library versions. And your company may change its name, change the product's name, or someone may drop the ball on renewing example.com.

• The web changes rapidly. The link you give is http, but in a few years its likely major browsers will only support https. Or we could all move back to the gopher protocol.

• Application troubleshooting does not always occur in an environment with internet access (or at least direct access to your domain).

• You mention your documentation is behind a "authentication" wall. Having to create an account on a website just to understand an error message is not pleasant (this is why SO doesn't require people to login).

Answer 4

There is a really successful way to approach this problem. Make sure the exception combined with the message are unique enough that pasting them into a web search can easily find all relevant posting about exactly this issue.

This is the secret reason I hate null pointer exceptions so much. Sure I hate that we even have to check for null but what bothers me the most is that, when I run into one, the only truly unique identifier I have to search on is a volatile line number.

Yes, I would like to be able to search for these. Oh sure, I know it happened because something was left null and then used. What isn't always immediately obvious though is WHY something was left null.

So sure, consider all these other documentation solutions. But the laziest thing you can do that will do me the most good is just give me something I can google.

Pretty Please?