When a customer opens a user manual, the idea that the text is lying or it is trying to manipulate them will hardly ever cross their mind. Who would want to lie in technical documentation and why?
The grim statement proclaiming that everybody lies proves to be true yet again. Here's what technical writers lie about.
Concealing Inconvenient Truths
This is a common story. Many technical documents depict their product in a much more positive light than it deserves. We naturally expect this from ads and landing pages that make everything look better and hide away any detail that can potentially spoil the impression. But being faced with this in technical documentation can catch us off-guard.
Avoiding mentions of things that don't work is one way. It hits hard when there's a common scenario that you expect from a tool, and it is not stated anywhere that it doesn't work, but it turns out it doesn't. The only thing you get from support is a clumsy workaround that they couldn't have added to their docs because it looks bad.
A similar situation happens when some features are described too vaguely and generally. This can easily mean that the mechanism behind is too complex and inconvenient to describe.
Sometimes lies are less toxic - tech writers can conceal facts not to cause confusion. For example, a tool's UI can offer four ways to perform the same action, but only one of them is documented. This is done not to confuse users with too many options.
A similar scenario can occur when, for some reason, one way of using a feature is more preferable for its creators. Maybe, it is more stable, and they've tested this scenario better. So, they are tricking you into doing a task in a certain way by “forgetting” to mention that other ways even exist.
But mind manipulation can be pushed to its limit when it comes to the dreaded lawsuits.
Avoiding Lawsuits
We already talked about how user manuals can serve the Legal department more than they do customers here. And this is the perfect example of content manipulation to get results.
It is usually characterized by redundant information and warning boxes and/or paragraphs that have no real value for readers. Their primary purpose is to have certain statements in the written form to show in court as proof.
Warnings are vital for user manuals. They can literally save people's lives. But piling them up in help topics is wrong. Besides, it is important to understand the difference between warning customers about the dangerous effects of a pill and giving minor warnings about software features. In the first case, all possible warnings should be documented — it has nothing to do with lawsuits, while in the second case trying to fit in every minor detail is not needed.
Conclusion
What should we consider a white lie, and what is a deviation from ethical norms? This is a philosophical question, indeed. Everyone acts and writes in accordance with their internal sense of what is right (or the tasks they get from the manager).
There's an opinion that people would hate technical docs that were a hundred percent true, like, "Well, you can try using this, but it's probably going to throw an exception. This feature is awesome but requires more testing. Our videos are so long because we never cut out the loading screens."
Not crossing the line is what technical writers should focus on here. Put clients first and there will be a pay-off.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices