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:
- It’s hopelessly subjective
- It makes people angry and ashamed
- It’s lazy and unimaginative
- 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.”
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):
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:
- Everyone knows
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…”
- Wordy phrases and unnecessary words
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.
You may have used or seen an ad for Grammarly. While it can be useful for detecting certain grammatical errors (and has a handy VS Code extension), it’s really designed for business communications and can struggle with technical language. It can also strip your writing of personality, so I’d steer clear of using it for your personal blog. I only enable it when I want to do one final check before putting a post live.
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.
I thought this one was too bad to be true but I’ve found multiple examples with this exact phrasing, and plenty more with variations including “BOOM, you've got some HTML!” and “BOOM! You now have your site hosted on [redacted] with blazing fast speeds, powerful CDNs, simple management, and ironclad security.” ↩︎