Thanks for complaining

Ever get the feeling that no-one reads your documentation? It’s a frequent issue amongst Technical Writers and the general stance reflects the approach many take to make sure that, when someone finally picks up the documentation, they can get to the information they need as quickly as possible.

Given that, there is little worse than to have errors reported in your documentation. After all, if they’ve only just started using it to help them solve a problem and one of the first things they spot is an error then it’s understandable that confidence drops and that they are less likely to go to the documentation in the future.

Of course we all do the very best job we can, yet the fact remains that mistakes happen, errors occur. The reason that this tends to be a bigger issue for information is down to how we process the knowledge we have.

Without getting into too much detail, learning is a continuous process and most of that happens when you are doing things, using the tools at your disposal and figuring out how they work and how they help you achieve what you are trying to complete. By the time you decide to check the documentation, you’ve (usually) got a good bank of knowledge already, and it’s building all the time.

So, when the documentation is wrong (regardless of whether the reader spots the mistake immediately or only realises it after trying out the instructions) it seems to be an obvious mistake. After all, if I can figure out how to do X, why is the documentation wrong for Y, it’s just the same process?

Software applications that have minor errors in them are tolerated because they are the tool and sometimes there isn’t an alternative. You learn how to accomodate those errors in the application and work around them. You can’t do that with documentation, it’s either right or wrong (ambiguous documentation is presumed wrong) so confidence in the rest of the information is linked to those initial few instances of usage.

We all have review procedures that should capture errors in the documentation, we do our best to think about how the user will be interacting with the product and base the structure and content of our documentation on that information, and we all receive that email that says “On page XY of the User Guide, it states that…” and our hearts drop a little.

However I think we should embrace those moments, be positive about them! You have a user who cares enough about the documentation to complain and I think it’s worthwhile thanking them for pointing out the error, tell them that it will get fixed, and encourage them to continue to let you know if they spot anything else.

So next time you get one of those emails, or a bug in the documentation is raised, be sure to follow up with the user and thank them. They are proving that people do RTFM.

Written By

Long time blogger, Father of Jack, geek of many things, random photographer and writer of nonsense.

Doing my best to find a balance.

More From Author

You May Also Like

1 year at Allied

Reasons to work

Hotel Life