Tips on Improving Technical Writing

Kesi Parker
Nov 14, 2018 · 4 min read
Image for post
Image for post

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:

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

Image for post
Image for post

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

Image for post
Image for post

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

Image for post
Image for post

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.

Image for post
Image for post

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:

  1. Never use a metaphor, simile, or other figure of speech you are used to seeing in print.

Technical Writing is Easy

Technical writing is for everyone!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store