Simply write better

If I asked you to compile two lists: one containing examples of good documentation and another with examples of bad documentation, I suspect the second list would be longer. I think this is because writing good documentation is hard and documentation can be bad for plenty of reasons: maybe it’s incomplete or out-of-date, or just maybe it uses unnecessary adverbs.

An adverb is a word that describes a verb, adjective or another adverb. Examples include ‘simply’ (‘simply drag and drop’), ‘easily’ (‘you can easily edit the config’), and ‘obviously’ (‘you obviously need this package installed for it to work’). If you’re overusing them, you’re not only upping your word count with filler, but you could also be alienating your readers.

Simply the worst

Jim Fisher’s 2018 talk at Write the Docs Prague in 2018, ‘Don’t say “simply”,’ gives four reasons not to use the word ‘simply’ in your documentation:

1. It’s hopelessly subjective
2. It makes people angry and ashamed
3. It’s lazy and unimaginative
4. It’s filler

Jim created a script to generate Pull Requests (PRs) against popular open source repos, removing occurrences of the word ‘simply’. While there was a negative response from some maintainers, others welcomed the changes – Taylor Otwell, the creator of the PHP framework Laravel, merged this PR.

But documentation is an ever-changing thing; since that PR was merged, 32 more occurrences of the word have been added to the docs.

Other ‘Inflammatory’ words

‘Simply’ is one of many ways to introduce your opinion into documentation when it’s not needed. While recently setting up a fresh Laravel project, I encountered this line:

“To make this a cinch, Laravel utilizes the DotEnv PHP library.”^[1]

Not only is ‘to make something a cinch’ a oddly informal, idiomatic phrase but it’s also completely unnecessary — I don’t care that the author finds environment configuration ‘a cinch’, I want to know how to do it.

In his talk, Jim lists some other words and phrases which can be similarly ‘inflammatory’ (not all of these are adverbs):

• Naturally
• Merely
• Of course
• Just
• Boom, you’re done^[2]
• Obviously
• Trivially

Chris Coyier also covers the topic in the CSS Tricks article, Words To Avoid in Educational Writing. As well as some of the above, he also adds:

• Basically
• Clearly
• Everyone knows
• Easy

Look at these two lists and strike these words from your technical writing vocabulary. They don’t add to your writing; in fact they’re probably detracting from it. I like this quote from Chris’s article:

“In educational writing, being clear and direct is valuable and appreciated. Skip the filler words and save the casual vibe for a time when you aren’t trying to explain something complicated.”

It's expected for documentation authors to express an opinion about the preferred way of doing something — this can be helpful — but it’s not their job to trivialise a task. The person writing a post or article on a topic is going to be far more familiar with that topic than a newcomer. If your reader finds something challenging, you’re not helping them by describing it as easy.

Cutting down on adverbs

If you’re already in the habit of using some of these words like I am, you might find it difficult to stop. Luckily, there are some useful automated tools which can pick up these mistakes. One of my favourites is write-good, a linter for english prose, designed to detect amongst other things:

• Adverbs (like ‘simply’) which can weaken meaning
• “Weasel words”: that make a claim sound vague or ambiguous. e.g. “Some people say…”
• Cliches
• Wordy phrases and unnecessary words

I use the write-good VS Code extension to lint my markdown posts, but it’s also available as a Chrome extension for use in Google Docs.

You could also try Hemingway App: a minimal editor which gives you a readability score as you type. It highlights adverbs and difficult to read sentences. It will even suggest simpler alternatives to overly complicated phrases.

The output of automated tools should be seen as a guide: you’re bound to get some false positives. That’s why, as well as technical solutions like those above, I also try to follow a few rules:

• Be aware of ‘the curse of knowledge’: If you are incredibly familiar with a topic, it can become difficult to remember that other people aren’t.
• Acknowledge the possibility of failure: not only do people make mistakes, but machines are set up in different ways. If you can’t make a process less error-prone, give guidance on how to recover from common errors.
• And finally, write what you’d want to read.