Don’t say “simply” in your documentation by Jim Fisher

Jim Fisher is a technical product manager at Pusher, and he gave a great talk at Write the Docs Prague 2018 about the drawbacks of using the word “simply” in your documentation.

Perhaps every technical writer has had this discussion at some point – ”don’t say simply” – and a hot debate rages over the correct use of “simply”.

For example, a piece of documentation could read: “Simply click the widget and you will launch the new build.” It’s the use of the word “simply” in this sentence, which would still be complete without it, that many people object to.

Why not say simply

But why not say simply? That’s a bold claim to make. Perhaps it’s just stylistic choice.

The main reason some people find it alienating because “simply” implies a task should be easier than it is. How do you know whether or not a task will be simple for your user?

We all slip into this habit even when we know saying “simply” is not a good idea.

There’s a good case to be argued that “simply” can also mean “only”, but this use of the term simply is ambiguous and therefore should probably be avoided.

“Simply” in the Mac interface

To illustrate his attitude towards the word “simply”, Jim told us the story of getting his first Macintosh computer.

Many of us can identify with the process of downloading a file on the Macintosh Operating System, and feeling disappointed when it doesn’t work straight away. We wonder – what I have I done wrong?

The reason for this failure to launch is you have to drag your new file to the application folder in order for the file to install properly.

Trying to install Steam in the Mac OS requires dragging and dropping to the Applications folder

In reality, the answer is a resounding no. What makes this process even more frustrating is the presence of the word “simply” in the interface.

“Drag and drop is – in theory – one of the simplest actions you can perform on a computer,” says Jim. “But is drag and drop actually simple?”

"Simply drag" arrow from the Mac OS

Jim’s story is an exercise in User Experience, which many find anything other than intuitive in the Apple Macs. Others with a different perspective love – nay, revere – the Apple brand.

Your attitude to Macs all depends on the preconceptions and expectations you have loaded into your brain when you start using a new system.

To use a Mac successfully, we have to learn the difference between an “installer” and a “program” – which isn’t immediately obvious when you try to install a new program. Drag and drop copies the installer file into the applications folder, and then launches the program.

There’s an extra step in the process which many former Windows users don’t know they should account for.

Dragging and dropping "iceberg" - only two actions are visible above the surface but more concepts are hidden below.

"In using the word 'simply', you are describing 'actions' and forgetting the concepts that are involved," says Jim.

If you’re only aware of the actions involved in a task you may forget about the concepts required to complete the action. Don’t use the word “simply” because you are probably describing actions rather than concepts.

Difference between simple and easy

Jim asks us whether drag and drop is actually simple. He defines the term “simple” as being distinct from the term “easy”. Most of us “mistake ease for simplicity,” says Jim.

Rick Hickey giving a talk called "Simple made Easy" where he distinguishes between 'simple' and 'easy'

The trouble is, when you’ve been working with an interface for a long time, you can fall into the trap of thinking something is simple – as well as easy. It can all just become part of the overall landscape you inhabit, where you stop noticing the quirks and idiosyncrasies. They become normalized.

It’s like how fish don’t notice they’re swimming in water. They never question its presence.

Software rests on many assumptions like this. But good UX is all about having empathy for your user and their unique experience – which can be tricky if you have a broad user base.

You need to take yourself out of your design bubble and figure out what experience users are really having with your software.

Is clicking really “simple”?

“We think of clicking as an atomic action” – but actually sometimes clicking requires a whole diagram to explain it,” says Jim. An atomic action is an action (in Computer Science) that cannot be broken down into any more steps.

And yet there is more than one way to interpret the act of “clicking” – as this configuration screen from an Apple Mac shows us.

Configuration screen on a Mac explaining to users that to 'click' involves tapping the tracker with their finger (rather than using a button)

One of the core issues many users have is coming from a place of only ever using a Windows operating system.

In Windows, you typically click the cursor using a button on the tracker. With a Mac, there are no buttons (you click by tapping your finger, or change the settings after the initial setup). It’s this tapping that many users can’t figure out.

So it turns out that a simple set up was not really so simple after all – unless you are familiar with the Macintosh Operating System.

Using the example of a Mac doesn’t explain the concepts it uses. So don’t say simply.

Reasons not to use “simply” in your docs

Language can be more inclusive overall by not saying “simply”. Here are four quickfire reasons not to use simply in your documentation.

The word “simply” can be subtly shaming. If users don’t find a task as simple as you tell them it is, this leads to feelings of inadequacy.

By implying your product is so “simple”, when it doesn’t work this makes people angry. We turn that anger inwards because we have no access to the original author – or nowadays we vent our anger on social media.

“Simply is hopelessly subjective,” says Jim. It’s a question of semantics, and although many individuals may not have a problem with the word “simply”, the fact that some individuals will misinterpret it makes it a problem.

It’s unimaginative to use the word “simply” when there are many other words that could do the job better. It’s also “filler text” which pads out your writing unnecessarily, and could be removed.

An experiment in removing simply

“I’ve been talking about Apple but I think this problem goes much deeper into developer culture,” says Jim. “Developers are infatuated with the word “simply”.”

To support this fact, he shows us that the word simply is used more than 92 million times on GitHub.

92 million mentions of "simply" on software version control site Github

Based on these findings, Jim decided to write a script to remove the word “simply” from code automatically. He had already used it on some other public repositories (including Laravel) with positive results, but it backfired in the case of Redis.

A comment from the founder of Redis taking issue with the "simply" script that Jim wrote

Jim found that he might offend people by telling them not to say simply. He learned that a script deleting your words is offensive and un-empathetic, so a key takeaway is to try to avoid forcing your views on others.

Potentially, it could be that over-focusing on the word “simply” is a tendency of wordsmiths, and asking people not to use it is putting too much pressure on people who might be struggling to write documentation in the first place.

A gentle education in the idea not to use ambiguous, potentially trivializing language is better than writing a script to remove the word “simply” from someone else’s documentation.

To avoid shaming your readers you should avoid simply in many cases and avoid shaming writers by writing potentially offensive scripts.

The solution to simply

To decide whether you should use the word “simply” could be turned into this equation:

Meaning + context + audience

If your word meaning is ambiguous in a certain context with a particular audience, leave it out and choose another – more definitive – word that has only one likely interpretation. This principle is a useful takeaway, instead of avoiding the word “simply” at all costs.

We could improve the documentation in the Mac interface by replacing the current text with “drag to install”. It would instantly make the UX much clearer by addressing at least one of the concepts needed to successfully perform the action.

“By including a link to talk to your company, you’re admitting the possibility of failure with your product,” says Jim. And that’s a good thing. Use more empathy in your language and show some awareness that things may not quite work as planned.

Focus on complexity and be honest in your language – admit that programming is hard. At the same time, be absolute in your language – show, don’t tell. Don’t leave any room for ambiguity.

Documentation for Jekyll sitemap admitting that programming is hard

Flag that something might be especially difficult – or in fact explain why you think it is simple instead of leaving it up to the audience to interpret.

One thing to note is that it’s frustrating when you tell people something will take less time than it does. Try to err on the side of caution if you’re giving time estimates for a task – estimate more time than you think, not less.

Overall, it’s best to avoid “potentially inflammatory words” in your documentation, which will only serve to frustrate your users if they run into problems. And they will.

List of inflammatory words

Final remarks

The key is to be as clear and concise in your documentation as possible. This will be an ongoing process. No piece of documentation is ever perfectly clear as this is one of the limitations of language.

You need to understand your audience and sometimes “simply” is appropriate, but use with care and caution. If you can use a different word that’s more precise, use that.

Empathy is the key ingredient when writing documentation. You don’t need a script to take out unnecessary words – you need humans to be the bridge between your users and your product.

Here’s a link to Jim’s full talk on YouTube, and you can follow him on twitter @MrJamesFisher.

Our knowledge base software KnowledgeOwl enables technical writers to publish outstanding documentation. Sign up for a free trial. 

Photo credits: Attribution-NonCommercial-ShareAlike 2.0 Generic (CC BY-NC-SA 2.0)