Using Simple Language in Technical Documentation

by Bradley Nice, Content Manager at ClickHelp.com — software documentation tool

First of all let me give you a quote from “20 Questions 20 Answers About Technical Writing” by Ugur Akinci, explaining the term of technical writing.

Technical Writing is a writing niche specialized in explaining how things work, and training others in how to perform specific tasks to accomplish selected goals or tasks.

Thus technical writing must be:

• Correct: all the information in a technical document must be accurate and verifiable empirically;
• Precise: a statement can be correct but not precise (e.g. Water freezes at low temperatures. This statement is correct but not precise. Water freezes at a temperature of 32 degrees Fahrenheit or 0 degrees Celsius. This one is both correct and precise);
• Relevant: information must be closely connected with the subject;
• Unemotional;
• Brief.

In order to meet the last condition you must ask yourself whether your writing is brief and easy to understand. To make your writing brief you should cut the unnecessary words. Let’s take a look at the following example:

(1) You can shorten that to “reviews”;

(2) As the readers we don’t get much information from this phrase, so we can take it out;

(3) “Examples” and “studies” are actually referring to the same thing so we don’t need both of these words.

(4) The word “methodologic” is unnecessary because in this sentence we talk about study design so it’s kind of implied that methods are going to be involved;

(5) You might thought that you’ve already used the word “illustrate” so you need another word with the same meaning. But this word doesn’t provide us with new information. So we should get rid of it and add “and” between challenges and solutions so they are both “illustrated”;

(6) If you think about it for a sec, any solution must be successful, so we can take this word out.

(7) “Difficulties” means the same as “challenges” mentioned above. And we’ve already mentioned that the paper is about cancer biology study design so we don’t need to mention “biological research” once more.

So we can shorten this sentence to:

Have a nice day!

Bradley Nice,
Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors