Implicitly downplaying knowledge in technical communication
Published on under the Writing category.
In technical writing and communication, every word matters; context, examples, literary devices all come together to help you convey a concept to a reader.
I recommend avoiding the words “just, simply, easy” and their variants in technical writing, particularly in print.
These words are usually redundant and add unnecessary assumptions to your content. Seeing words like “just” or “simply” are discouraging, particularly to people who have limited knowledge of the subject matter.
Consider the following two sentences, both pertaining to the target audience for the IndieWeb community:
You just need to have your own website or be interested in setting one up.
To join, you should be interested in personal websites. You do not need to have a site!
In the first example, I use “just”. This is inappropriate because “just” setting up a website or having one is a big step. Setting up a website is non-trivial.
In the second text, I convey the same information — an interest in or having a personal website is a requirement for joining the community — but the second sentence is more encouraging and less presumptuous.
The first sentence was from my writing two years ago. Since thinking more about this subject, I have become more proactive in catching when I use redundant words. When I notice I use a word like “just” or “easy” (in context such as “Getting started is easy.”), I remove them.
Let’s walk through one more example:
I asked for a specific format, so as to ensure the prompt was easy to parse.
I asked for a specific format, to aid in parsing the prompt.
Again, I’m conveying the same information; the delivery is different.
Avoiding words like “easy” and “just” are an essential part of technical editing and communicating. Our goal is to empower people with knowledge, and doing so necessitates our recognizing the amount of work it has taken ourselves to learn what we know.
Comment on this post
Respond to this post by sending a Webmention.
Have a comment? Email me at email@example.com.