Just Simply – Stop saying how simple things are in our docs

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.

You’re keen to share your excitement!

When I’m writing technical docs, annoyingly, I find myself putting “just” in all the time, despite having strongly-held views about words such as this. I think it’s because I’m so keen to share my enlightenment. It’s exciting that the code I’ve written might be able to help, and naturally I’m keen to communicate that. A bit of light editing lets you keep the enthusiasm for the code, lose the bits that could be interpreted as condescending, and improve the clarity, to boot.

from Hacker News https://justsimply.dev/