Technical Writing

Technical Writing

An area of business writing that can be very daunting is the writing of technical documents. With the right approach, however, the problems are easily overcome.

Good technical writing is purposeful and is directed towards the reader. It provides specific information on a technical subject to particular readers for a specific reason.

The style of writing can be quite different from other business writing. Examples include educational materials, business plans on a technical issue and test results. There are two main objectives:

  • educate readers about your message
  • bring about change in the readers’ behaviour and attitude

The subject can be tangible, for example a software program, or abstract, for example steps needed to finish an office process.

When writing a technical document, the readers’ needs and experience should be at the front of your mind. The language and tone will be affected by who you are writing for. Is it someone who:

  • will understand more detail or need to test your products or processes?
  • builds or operates a machine?
  • will look at the business side, making decisions about viability?
  • is merely interested in a product?

The failure to consider the reader and their needs is often a reason for poor technical documents. The essay and academic styles learnt at school and used at university are not appropriate or helpful in writing a technical document in the modern business world. Too much use of jargon that readers may not understand can be a problem.

Once you have defined your reader and purpose, you need to gather the information required and plan your document before you begin writing. A Mind Map is a useful tool for planning your document. It will help you gather and structure your information on one sheet of paper or screen. Also, the Mind Map structure is free flowing, so it uses both sides of your brain.

Always use Plain English where possible. If you can’t avoid technical terms and jargon, make sure they are defined well when first used. Use a glossary where necessary. Use short sentences with only one idea per sentence. Paragraphs should have only one topic in them.

Things to avoid:

  • vague language makes a document hard to follow, so be clear with your words
  • negative language, for example ‘Do not leave access lid unraised.’ Instead write ‘Raise access lid’
  • padding, the unnecessary use of words makes the document long and difficult to read

A good guide to measuring how easy or hard a document is to read is the Gunning Fog Index

[GFI]. This index measures sentence length and polysyllabic words. Documents with shorter sentence lengths and fewer long words are easier to read. A good technical document should have a GFI of 14 or less.

Another measuring tool is the Flesch Reading Ease Score [FRE]. This also measures the use of long words and sentence length. The scale is 0-100. The higher the score the easier the document is to read. Remember that both the GFI and FRE do no measure the effectiveness of the document, only the readability.

There are many courses available that teach technical writing skills. If you write a lot of technical documents, it is worth going on such a course. One that includes the teaching of both Mind Mapping and GFI is better.

Use specific titles and lots of white space. This helps the eyes to stay focused and aids understanding. The use of graphics can also help – after all, a picture can tell a thousand words. Using these simple techniques means your document will be easier to understand and follow.

In summary, don’t listen to the myths about technical documents. It is not true that the longer they are, the more impressive they appear. Longer documents are not always useful, nor are they the only way to present information. Executives do not necessarily like reading long documents.

Be effective with your language and use an economy of words. You do not want to bore your reader. A good technical writer can make complex information easy to understand and a difficult task easy to implement. Good technical documents will engender confidence in their readers and the readers’ ability to follow a process.

2017-03-03T13:17:59+00:00