Basics of Plain Language in Technical Documentation

Technical writing or technical communication is about delivery of technical information to the general audience. Using plain language in technical documentation allows to make the writing clear, concise and helpful to readers.

Plain language writing helps the target audience easily perceive information, avoid misunderstandings and save time, because it gets the job done the first time.

Defining Plain Language

Professor Robert Eagleson, former Associate Professor of Modern English Language at the University of Sydney describes plain language as following:

• Plain language is clear, straightforward expression, using only as many words as necessary;
• It is language that avoids obscurity, inflated vocabulary and convoluted sentence construction;
• It is not baby talk, nor it is a simplified version of the English language;
• Writers of plain English let their audience concentrate on the message instead of being distracted by complicated language;
• They make sure that the audience understands the message easily.

Plain language is writing that the intended audience can understand and act upon the first time they read it.

One of the types of technical writing is legal writing. Its distinguishing features include the tendency toward excessively complicated grammar and overformality. Compare the following examples to get the idea of the plain language writing.

The first two paragraphs contain superfluous information that is unnecessary for the reader, and only the last paragraph implies the purpose of the message. Moreover, the whole letter is written in an overly official manner with long sentences, uncommon words and clichés, which make it hard to read.

Let’s see if plain language can improve this piece of writing.

The official message contains 153 word, while the plain language version uses only 77. Both messages are broke into 3 paragraphs i.e. 3 ideas, which were carefully preserved in the second version. It is as well obvious that the second message is much easier to read and to scan through. All these benefits are achieved by the means of plain language.

Writing Plain Language

Microsoft Manual of Style provides the following recommendation: “Use simple sentences and short words. Use keywords that users use and can relate to. For example, they want to “download,” not to “experience the latest innovations.” Also avoid technical terms and jargon that users may not understand and wouldn’t search for.”

These are the quick tips for plain writing and these are obviously not enough. That’s why we’ve compiled our own list of 11 tips of plain writing.

Plain Writing Tips

1. Put important messages at the start;
2. Write short sentences (15–25 words on average);
3. One sentence — one idea;
4. Vary the rhythm (consider very short two- or three-word sentences);
5. Break the text into small chunks (One paragraph — one idea);
6. Avoid making nouns from verbs (nominalisation);
7. Avoid jargon. Replace it if possible, if not — ask yourself if it is necessary. If you must use a technical or specialised term, explain its meaning the first time you see it;
8. Avoid long words. Use words with more common use, i.e. use instead of utilize;
9. Avoid acronyms. If a potential acronym appears three or more times in a single paragraph, it may be okay to use it. Make sure you explain it at every point the reader might join you;
10. Cut out redundant words;
11. Use the active voice.

Now it’s Your Turn

Remember, that documentation should be easy to read. Use words economically and at a level the target audience can understand. Also make sure that the sentence structure is tight and the design is visually appealing.

Good Luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices