Regarding "Simply" and "Just" In Documentation

By | November 28, 2012

When reading documentation, manuals, narratives, instructions, tutorials, and the like, I frequently see phrases like: “If you want to do X, simply …” and then several steps of instructions. Or, “In order to do Z, just do this, that and the other.”

You don’t need the words “simply” and “just” in your writing. If the instructions are simple, they will *look* simple. If they are not, using “simply” and “just” indicates that the writer *wants you to think* they are easy. They are marketing words, reflecting the way the author wants you to think about the work, and are not descriptive of the work itself. Eliminate these words (and their various variations) from your writing, and your meaning will be much clearer.

8 thoughts on “Regarding "Simply" and "Just" In Documentation

  1. Pingback: Regarding “Simply” and “Just” In Documentation | codegooroo

  2. Loren Lang

    I would argue that they are not only unnecessary marketing words but can be interpreted as elitist and condescending. For many beginner users of whatever the documentation is for, “simply” doing whatever the docs say can be anything but simple.

    Even as a tech veteran of 20+ years, I have recently gone through one of the most mind-bogglingly frustrating experiences in my life when the docs for a particular technology that I’ve not worked with before now assumed so much knowledge of details on my part that I very nearly decided to hang it up and choose a different product.

    I’m increasingly convinced that nothing should ever get released to the public until the developer’s grandmother can sit down with the docs and have it installed and running without assistance.

    Reply
  3. Peter O'Callaghan

    I often find myself writing both those words when I’m providing answers on Stack Overflow and in other forums. I try to take them out when I realise, because I know how annoying it is when I’m getting frustrated trying to achieve something that I’m being told is ‘simple’.

    Reply
  4. Hari K T

    A most controversial one . But I will say the words simply etc may not be marketing. It may be according to the locale slang or sometimes the way the author narrates stuffs.

    But I will try to take your words when I write anything new in the future.

    Thank you for the tips.

    Reply
  5. DJ Sipe

    I completely agree. What really gets under my skin is any time the user (myself included) is made to feel dumb by not “getting” how to use or understand some piece of technology.

    I like to think that I’m a pretty bright guy. So if a product or documentation is confusing or unintuitive to me, I see that as their fault not mine.

    Reply
  6. Till Klampaeckel

    I agree on the use of those words and if you take a minute to think about it, it makes sense but I would argue that the use of these words is not intentional or at least they were not put there the way you understand them.

    This could be a case of “lost in translation” as well. Not everybody on the Internet is a native English speaker. We (non-native English speakers) make mistakes. So for example, the German word “einfach” is not used to make people feel dumb. It’s used because the author described a couple (simple :-)) steps.

    There’s also something about feeling offended on the Internet when there is no reason for it.

    Reply
  7. A Writer

    Writers simply don’t get it. If they could just follow your recommendation docs would be better.

    Reply
  8. Heikki Naski

    Not to mention that when the instruction doesn’t work for some reason, you probably get more annoyed if the doc says: “just simply do these easy steps and everything just works”.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *