Plain English is clear and concise English.
Technical writing is different from creative writing. The goal of technical documentation is to make complex technical information easy to understand. Hence, Plain English is an important aspect of technical writing. It makes your document more accessible, consistent, and readable.
Why Plain English?
English is not the first language for many people. More people can understand Plain English compared to sophisticated English.
Plain English is easier to translate. Common English words and phrases are more likely to have equally common counterparts in other languages.
Plain English is easier to comprehend. Readers can focus on understanding the technical concept instead of decoding the sentence.
Basics of Plain English
Full Stops instead of Commas
- Use short sentences whenever possible.
- Avoid combining more than 2 sentences with a comma.
Active Voice instead of Passive Voice.
For example, prefer
"X() reads a new file"
over
"A new file is read by X()"
Cut the Adjectives
Most adjectives do not convey relevant information. For example,
"This well-written function reads a new file"
can be shortened to
"This function reads a new file"
Get to the point quickly and stick to the point.
Inclusive Language and Biases
- Avoid using pronouns altogether. If you need to, then:
- use "they" instead of "he" or "she", and
- "folks" or "people" or "everyone" instead of "girls" or "guys". See heyguys.cc.
- Avoid racist terms like "blacklist", "master", "slave", etc.
- Avoid phrases like "it's as simple as...", "this is an easy step...", etc. What is easy for one person, may not be easy for someone else[1]. Let's not discourage learners by using these terms.
- Actively check for biases in your writing. For example, sample names may have gender or racial biases depending on the context. As humans, we may never be completely unbiased. It is still important to educate ourselves and keep trying.
Avoid Jargon, use Common Words
Technical documentation has a lot of technical jargon. Let's not add more. One way to reduce jargon is to get feedback from a diverse range of readers.
Note that slangs are also jargon.
Extra Tips
Planning
It is good practice to plan a document before you start writing. Think about the following:
- Intended audience
- Scope of the document
- Broader context
Structure
Start with a rough structure. Try to split each concept into a distinct section. Clear structure and headings improve readability.
Style Guides
Style guides are standards to help maintain consistency in documentation. Consider adopting a style guide for your technical writing projects, even personal blogs.
[1] I have used "easy" in this blog post. But, note that I'm using it in a comparative context. I say: Understanding Plain English is "easier than" understanding sophisticated English.
Top comments (0)