Tips on Improving Technical Writing
To write clearly is the main goal of technical writers. That’s why I want to give you some pieces of advice that will improve your technical writing skills and your documentation, and, as the result, people will read it from cover to cover.
Know Your Target Audience
Nowadays, documentation is used in all spheres, for example, in IT, engineering, and even in the aerospace industry, and a technical writer’s aim is not just to write documentation because their boss said but because people need it.
Your audience’s level of knowledge, vernacular, and physical abilities influence on various aspects — what vocabulary, text colors, and fonts should be used. Here is a series of articles that are dedicated to things discussed so seldom in technical writing:
- Technical Documentation for People With Dyslexia
- Technical Documentation for Color Blind
- Technical Documentation for Visually Impaired
- ‘Let there be color!’
Stick to Technical Writing Style
Technical writing differs from general writing, academic writing or other styles. Technical writing style includes many aspects that you should keep in mind. Unfortunately, I can’t describe all of them because this topic is wide-ranging but I will try to clarify the key rules.
Use Plain Language
As I’m mentioned above, your readers will be versatile, so, the structure and vocabulary of your documentation should be clear and plain from the very beginning. If you start with complex descriptions and think that “Well, if they read the whole sentence they would understand”, you’re wrong, people just won’t keep reading. If you want to write documentation that everybody will read, here are some examples:
Important Information First
Unclear:
The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety.
Clearer:
Danger! Stay away from cliff.
Clear Sentence Structure
Technical writing style is about short simple sentences — long ones may confuse readers, and it makes remembering information difficult.
No:
Furthermore, large volumes of water are also required for the process of extraction.
Yes:
Extraction also requires large volumes of water.
Forget About Passive Voice
Active voice is preferable in technical writing because it clearly shows the actor in a situation that makes documentation easier to understand.
Passive
The file is edited by the administrator.
Active
The administrator edits the file.
Manuals of Style That You Should Read
The Chicago Manual of Style
The Chicago Manual of Style (abbreviated in writing as CMS or CMOS, or verbally as Chicago) is a style guide for American English published since 1906 by the University of Chicago Press. In the United States, it is the most widely used style guide for non-journalistic content.
Microsoft Manual of Style
The Microsoft Manual of Style for Technical Publication (MSTP) is widely used in the technical environment. The first edition was published in 1995.
Associated Press Stylebook
The Associated Press Stylebook and Briefing on Media Law, usually called the AP Stylebook, is a style and usage guide used by newspapers and the news industry in the United States. It is not widely used outside of journalism.
The 10 000 Word Method
Of course, it’s easy to say “Write simply, and everything will be great” but it’s difficult to stick to this rule, especially when you describe something complicated, for example, a spacecraft. Have you ever read such manuals? I’m sure, you think that they’re difficult and written only for those who have relevant education. I want to show you a great example of the “space car” description, the author explained it using only those words that people use the most often.
I’m not good at the space theme but it was interesting to examine it, and your manual should be the same — clear, obvious, simple, and interesting at the same time.
As you see, you don’t need many words to explain difficult things but it requires great efforts. If you want to try yourself, here is a website with those popular 10 000 words and a checker.
Conclusion
To sum up all the information, here are George Orwell’s general writing rules that greatly work for technical writing:
- Never use a metaphor, simile, or other figure of speech you are used to seeing in print.
- Never use a long word where a short one works.
- If it is possible to cut a word out, do so.
- Never use the passive voice. Use active instead.
- Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
