GUIDELINES FOR TECHNICAL WRITING

 

Good technical writing uses precise and factual language. The following guidelines will help your readers understand what you write.

USE JARGON APPROPRIATELY

Jargon refers to word use that is specialised or appropriate to a particular group. Jargon is a hallmark of technical writing, and its use is desirable in that it facilitates communication between members of a group.

Writers must be certain, however, that readers are familiar with any specialised terms used in a document. Documents that contain ‘jargon’ may seem obscure or pretentious to readers outside the field. If you are writing for a broad audience, define new terms or, if possible, substitute more general terms.

USE GENDER NEUTRAL LANGUAGE

The days when writers used ‘he’ to refer to people in ‘masculine’ occupations and ‘she’ to ‘feminine’ occupations are long gone. When you refer to a person’s job title, don’t make a gender judgement, use neutral terms. Your nurseryman could well be a woman, and your nursing sister, a man. Examples of gender neutral language include:

- Firefighter instead of fireman

- Salesperson or sales representative instead of salesgirl, saleswoman or salesman

- Flight attendant instead of air hostess or steward

- Police officer instead of policeman or policewoman

- Spokesperson instead of spokesman

- Synthetic or artificial instead of manmade

- Worker instead of workman

USE SIMPLE SENTENCES

The more complex a sentence, the more difficult it is to understand, especially for readers unfamiliar with the topic. Some novice writers, especially those trained in academic writing will try to impress readers with long, complicated sentences. If you find yourself falling into this trap, double check your sentences to see if there is a more direct way to write the same thing. Imagine how someone would actually say the sentence in conversation. For example, while a typical report might state “It was known by his supervisor that the equipment was faulty”, few people would say that it like that. Most would simply say “His supervisor knew the equipment was faulty”. Writing a sentence in this way provides a clearer and more direct message for readers.

AVOID PASSIVE AND UNNECCESSARY WORDS

Similarly, use simple, straightforward words and expressions. For example:

- Use instead of utilise

- Begin instead of initiate

- Person instead of individual

- Now instead of at this point in time

- Because instead of due to the fact that

- Consider instead of give consideration to

- Investigated instead of conducted an investigation

- Apply instead of make an application

Avoid unnecessary repetition of words (redundancies). For example: end results or final results, red in colour, in order to, refer back, all of, join together.

USE AN ACTIVE VOICE

Active voice is one of the cornerstones of clear writing. In technical writing it is nearly always preferred to passive voice. Using an active voice gives your writing authority and verve. It speaks directly to readers, leaving them in no doubt who or what carried out the action.

Active or Passive Voice?

Voice, in writing terms, refers to whether the subject of the sentence acts or receives the action.
In active voice, the subject does the action; for example: ‘The manager recommended an investigation’.
In passive voice, the subject receives the action; for example: ‘An investigation was recommended by the manager’.

By comparison, passive voice lacks clarity and emphasis, although there may be occasions where you will use it, particularly in cases where the subject is unknown or less important than the action. For example, ‘The connector cord is constructed from a flexible, heat-resistant material’.

USE IMPERATIVES

Imperatives are instructions or directives. They tell the reader what or how to do something. For example, ‘Read the following instructions’.

The difference between imperatives and active voice is that active voice makes a statement but gives no directive to the reader. For example, ‘The instructions describe how to assemble the machine.’

Use imperatives when you write instructions, procedures and operating manuals. In these documents, the reader needs clear, unambiguous instructions, and will be thankful for your guidance.

SELECTING FIRST, SECOND OR THIRD PERSON

Deciding whether to write in the first, second or third person depends on how formal you want the document to be.

First person – I, me, we

Second person – You

Third person – He, she, they, them

First person writing, using I’ or ‘we’, means the writer has a central role in the document, therefore the writing cannot be objective. First person writing is used in reports, memos, business letters, and some types of academic writing, where the writer wants to establish his or her credentials or opinions.

Writing in the second person means you address your reader directly. It gives the document a casual, friendly tone, which helps the reader to focus on the content. It is appropriate for writing instructions, memos and how-to manuals. However, this style isn’t appropriate for other, more formal, types of technical writing.

Academic writing, scientific reports, business reports and some types of reference books usually require a more detached, measured tone. You don’t need (or want) to create a personal bond with the reader in these types of writing; certainly the reader will not want to be overly aware of your presence. Second or first person writing would most likely sound presumptuous, awkward and unprofessional. Writing in the third person creates an appropriate sense of distance or formality between the reader and the writer.

USE CORRECT SPELLING, GRAMMAR AND PUNCTUATION

Correct spelling is essential in all types of technical documents. Misspelt words are distracting, unprofessional and potentially misleading. Use a dictionary if you are unsure of a word, and take especial care with unfamiliar technical terms and people’s names. Use a style sheet (see Lesson 6) to ensure consistent spelling throughout the document.

Grammar is the set of rules that is generally agreed on in any language. A good writer will:

- Keep sentences short and clear.

- Vary the length of sentences.

- Use the correct syntax (i.e. the correct arrangement of words in a sentence).

There are many rules covering grammar – learn them and if you’re still not sure if something conforms to ‘good English’, use common sense. If a sentence sounds clumsy or wrong, then change it!

Punctuation marks are designed to aid the reader’s understanding of the text. Poor punctuation obscures the meaning and destroys the reader’s train of thought.

All writers must know the correct use of punctuation marks. As a starting point, make sure you know exactly how to use the common punctuation marks: commas, full stops, semicolons, colons, apostrophes, brackets, hyphens, question marks, and quotation marks.

Technical editors must also be familiar with the less commonly used punctuation marks, such an en rules, em rules, ellipses and solidus.

Learn more: Click here to see our Technical Writing course