Make Your Writing More Approachable for Learners

If you're creating technical content in order to teach others, you might be tempted to use words like "easy", "simple", or "straightforward" because you want to put the learner at ease. Unfortunately, those words can have the opposite effect.

How "easy" something is depends on the learner's frame of reference. It's relative to their existing experiences. When a learner encounters something that they hear is easy, or simple, or straightforward, and they encounter a problem, they tend to internalize it; "This is easy... why am I struggling? I'm not cut out for this!" This cancels out all the good intentions you had.

When I'm editing a document, article, book, or script, I have a list of words and phrases that I try to eliminate right away. I call them "bad words". Here are some of the words that tend to be demotivational.

• basically
• easy
• just
• obvious
• obviously
• straightforward
• simple
• simply

I flag these and remove them, as in most cases they're not necessary. For example:

Simply reboot the server.

Remove "Simply" and the sentence loses no meaning and becomes tighter:

Reboot the server.

Sometimes I'll ask the author to add the context that might be missing. A lot of times, authors are making assumptions about the experience the readers have. Consider this passage:

Using Okta is a simple way to add authentication to your app. Just add it to your project. Much easier than writing your own authentication.

If you look at the documentation for Okta, it's anything but simple. And you don't "just" add it to your project. You need an account. You need to create users. You need to import the appropriate libraries, and integrate the code into your codebase.

If you've done this a hundred times, you may indeed find this easy. As an author, you have to remember that you're writing something like this to teach others. You want them to be successful. So you may have to share the details so the learner has the right frame of reference, and can make the call if it's "easy" for themselves. Consider this version instead:

Okta lets you add authentication to your app instead of writing your own logic, which will be more complicated and more prone to security vulnerabilities. In this tutorial you'll sign up for an Okta account, obtain the API keys you need, create your users, and integrate Okta's JavaScript code with your app.

This version tells the reader what's in store, including an explanation as to why Okta is a good choice over writing your own implementation.

Yes, it's much more text. But readers can skip it. Assume your readers are as smart as you. Give them all the pieces and let them decide what's easy, and what they can skip.

I suggest adding words like "easy", "simple", and others to your text editor's spelling dictionary as misspelled words so they show up as you're writing or editing.

You can also install plugins for your editor that focus on improving writing. The write-good plugin for Visual Studio Code is handy, and you can find similar plugins for Vim and Emacs. These will find some of the words I listed, among other phrases and words that cause your writing to be weaker than it could be. Be warned though; these plugins have opinions of their own, and may ignore some words while flagging others. Tweak them to find what works best for your learners. After all, you're writing for them, not just for yourself.