DEV Community

Brian P. Hogan
Brian P. Hogan

Posted on • Originally published at

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.

Discussion (5)

georgewl profile image
George WL

This is basically easy and just a obvious and obviously straightforward and simply simple method, I love it.

Edited to remove the crap and it becomes so much nicer and removes the chance of coming across as sarcastic or belittling:

This, I love it.

fyodorio profile image

Yeah, it always drives me mad when I see titles like ”Easy-peasy authentication with JWT my neighbor 5yo had told me about”. It’s hardly ever aligned with reality.

jennapederson profile image
Jenna Pederson

This is awesome Brian! Thanks for sharing this.

yujiri8 profile image
Ryan Westlund

These are really interesting thoughts. I'll keep this in mind from now on when I write tutorials.

aminarria profile image
Amin Arria

Love it! Usually when working with more junior developers I have to constantly remind me to not explain things using those words