Tip 39 - smarty pants

Aug 1, 2024

Why do so many contributions to documentation sound like someone trying to “be smart?” I think people naturally tend to use “elevated” language because they think of docs as “very serious reference material.”

Docs isn’t Shakespeare… or is it? Shakespeare’s writing only sounds “fancy” to us now because the language of their time is so different from the language of our time. Shakespeare’s plays were not written to challenge the audience. They were entertainment, and not always of the highest form.

We may work with complex or abstract subject matter, but our docs writing is meant to be understood. There is no point in having docs that aren’t consumable by our readers.

One PR suggestion I’ll often make is to simplify word choices and phrases so that the meaningful words stand out. Don’t waste your reader’s energy on “harder” forms of words that distract from the project or industry terms that we can’t simplify without losing meaning. Some of your sentences will be challenging enough for some of your readers even when they are as clear and concise as possible!

✅ You can access the Cloudflare bindings and environment variables through the Adapter API.
😐 You have the posibility to gain access to all the Cloudflare bindings and utilize any previously configured environment variables through the Adapter API.

These sentences may feel awkward to write. (“This is “official documentation” — am I being “proper” enough?” “If I write too simply, will my audience feel talked down to?“) But, for the ones who need it, this may be the difference between them being able to use your project and being forced to give up.

And the ones who don’t… most of the time, they won’t even notice. They’ll have a great “no fluff, just stuff” experience.

No one ever complained because docs were too easy to read.

See the whole list of tips!

Toggle Comments