How to Fix Confusing Docs and Products
Working in tech, I find many docs and products are confusing. Most of the time, the language itself is clear. “First do this, then do that, and voila!” Users still feel confused. The cost of confusion is high: Users will either abandon the product, or require a lot of handholding and troubleshooting from the developer.
On the other side, developers might feel puzzled too: “Are users just … dumb? I’ve already clearly listed all the actions! What else can I do? Oh, should I just build an LLM agent to automate EVERYTHING?” ( — nope, you shouldn’t. But that’s for another post)
In this post, I will (1) explain the most common cause of user confusion and (2) a simple way to make your docs easier to understand, and your product intuitive to use.
Mental Models
Often, confusing docs read like the following paragraph — readers understand every word, every sentence, but still feel confused.
Read the following paragraph, and see how you feel while reading it. Don’t skip. Read it. It’ll be worth it.
A newspaper is better than a magazine. A seashore is a better place than the street. At first it is better to run than to walk. You may have to try several times. It takes some skill but is easy to learn. Even young children can enjoy it. Once successful, complications are minimal. Birds seldom get too close. Rain, however, soaks in very fast. Too many people doing the same thing can also cause problems. One needs lots of room. If there are no complications it can be very peaceful. A rock will serve as an anchor. If things break loose from it, however, you will not get a second chance.
In a room of ~50 MBA students, usually, only one or two could figure out what this paragraph is about. Now read it again, knowing it is about flying a kite.
If you did the exercise the second time, the same paragraph would read much better. The big difference is that the mental model of “flying a kite” helps readers understand it better.
The Curse of Knowledge
A mental model is an internal representation of how a system works.
The Curse of Knowledge happens when the expert communicates with the mental model in their head, but the mental model is not explicitly spelled out to the reader. With every instruction step, the expert can “autocomplete” the corresponding mental model and fill in the gaps. However, the reader cannot do the autocompletion. As a result, readers feel confused, while the expert thinks everything is already very clear.
The curse of knowledge is especially problematic when the expert creates something entirely new that requires an unknown mental model for the user. In this case, the user has minimal experience to latch on. Instructions alone (without explicitly explaining the mental model) will lead to confusion.
How to Solve This Problem?
(1) (In doc) Explain the mental model: How the system works.
How detailed does the explanation need to be? The explanation needs to enable users to OPERATE on the system, but no need to go deeper.
For instance, for users to operate a car, you need to explain the wheel, the brake, and the accelerator — and how the car changes accordingly. But you don’t need to explain how the engine or transmission system works.
(2) (In product) For every user action, users should be able to inspect the result of the action. Close the Action -> Result loop. This allows users to test if the system changes consistently with their mental models.
Some common operations: CRUD (create, read, update, delete)
A common fail mode of confusion is the system not providing any feedback to the user on the result of the action. In this case, although the expert can autocomplete what’s happening under the hood, the user will be left hanging, confused if they have done the right thing or if the system is working as they have hoped.
With a clear mental model:
- Users will understand not just what to do, but why.
- They can predict system behavior and troubleshoot independently.
- Your product becomes intuitive and delightful to use
The curse of knowledge isn’t about intelligence — it’s about identifying the mental model gap between expert and user. You’ll transform confusion into clarity by (1) making your mental model explicit and (2) ensuring every action has inspectable results.
