Let's stop saying 'It's Simple!' in technical documents
Imagine you’re trying to use some new software.
You’re reading through the docs while it downloads. The docs seem like a straightforward list of instructions for getting up and running…not much explanation about everything the software can do, but maybe that will be clearer when you’re actually using it.
Finally! You open terminal or command prompt and type in the first command, following the instructions exactly. Nothing happens. Maybe you read incorrectly. You try again. Nothing happens. You go back to the docs, check again, and try a third time. Nothing happens.
You scour the docs for an idea of what might be causing the problem but don’t find an answer. It’s just the list of instructions, with no mention that the instructions might not work. Your frustration increases. Something’s wrong, but what? As you think about how to start troubleshooting, your eyes wander to the top of the instructions.
The first sentence says, “Ready to get started? It’s simple!”
Fellow technical writers, we can do better. Our goal might be to make it simple, but we can’t assume that we made it simple for everyone, and we shouldn’t be telling readers that it’s simple. Our readers are the judges of that, not us! Anyway, if it’s so simple, why are tech writers involved?
Even when you write clear documentation, it might not be simple. Maybe the user interface changed or there’s a new step in the process, but no one mentioned it to you, so the current documentation is incorrect. Maybe the software has a bug. Maybe the readers have less experience in the field than you thought. Your documentation can be clear but not simple for many reasons.
When you tell readers that something is simple, but it’s not simple for them, here are a few other things you’re telling them:
- We make a difficult, frustrating product, but we don’t realize it (or maybe we don’t care).
- This is what you can expect if you keep working with us.
- Give up! This is too hard.
- This product is not for you.
- Find another solution as soon as you get the chance.
Technical writers seem to use “it’s simple” (and “it’s easy” and similar phrases) to reassure or encourage readers as they work through the documentation. I think this is unnecessary. If your instructions and explanations helping readers understand and use your product, they will be reassured and encouraged just by making progress. There’s no need to tell them what they’re experiencing…or about all the simplicity they’re enjoying.
I also see “simple” used to describe product features. For example, “Product X is a simple way to [do something].” The problem has two parts: “simple” doesn’t give readers much information and it isn’t objective. What makes it so simple, and how do you know? Is it a one-step process? Does it mean we can stop using seven other products? Does it solve a problem or eliminate a roadblock?
Why not just tell readers what it does and how to use it, and let them decide whether it’s simple?
About the image used in this post:
Scream Zone Sign at Night by Amaury Laporte is licensed under CC BY 2.0.