As a developer, I often find myself knee-deep in a new technology – perhaps investigating a library, or learning a language. I’m trying to frame new concepts in my head, applying my own data and architecture on the fly to the generic explanations in the docs. It’s hard! Which is why it’s jolting to read something like:

• [This library] makes it painless to [do difficult thing].
• [Complicated thing] made simple and easy.
• All you have to do is just [difficult thing].

If someone’s been driven to Google something you’ve written, they’re stuck. Being stuck is, to one degree or another, upsetting and annoying. So try not to make them feel worse by telling them how straightforward they should be finding it. It gets in the way of them learning what you want them to learn.

When I’m writing technical docs, annoyingly, I find myself putti