Using the correct language

From TechWriter Wiki

Jump to: navigation, search

Contents

Introduction

For many people outside the Technical Communications industry, one of the primary reasons for engaging a Technical Writer is to ensure the correct use of language. Although it is certainly not the only skill we posses, the correct use of language is undoubtedly the most visible facet of our craft. Whilst mistakes or irregularities in other elements of a communication may be forgivable (even if not entirely justifiable), there is absolutely no excuse for poor use of language from a Technical Communicator.

This page provides some general guidelines for the correct use of language in technical communications, and some specific guidelines for specific types of technical communications. However, it does presuppose a solid grounding in English grammar - without such a grounding, any communication (technical or otherwise) will always run the risk of being substandard.

Choosing the correct words

Descriptive writing should be in the third-person, active voice, indicative

Descriptive technical writing is writing that explains how something works, or how a particular activity is carried out. This is distinct from instructional writing (see below), which explains how to do something.

When writing a technical description, use the third-person active voice, indicative. For readers for whom lessons in Grammar are a dim and distant memory, the following explanations may help:

The third person
The third-person is: He, She, It or They. Writing in the third-person means that the (grammatical) subject of the sentence is the person or thing that is being discussed.
Active voice
Using the active voice means that the subject of the sentence is the person or thing that carries out the action expressed by the verb. Using the active voice therefore focuses the reader's attention on who or what is carrying out the action (which is the purpose of descriptive writing). The opposite of active voice is passive voice. Using the passive voice, the subject of the sentence is the person or thing being acted upon (by the verb). This type of writing tends to be less 'direct' and is rarely used in technical communications.
The indicative mood
Using the indicative mood simply means stating facts, which is, of course, what all good technical descriptions must do. More generally, this means ensuring that each sentence in a technical description is making a statement that is demonstrably true, and that does not leave any scope for interpretation (or misinterpretation).

Examples:

Avoid Use Instead
The application is signed by the Sales Manager. (Passive voice) The Sales Manager signs the application to approve it.
You approve the application by signing it. (Second person)
The Sales Manager can sign the application to approve it. (Mood is not indicative)

Instructions should be in the second person, active voice, imperative

Instructions must always command the reader to do something. Typical examples are operating instructions, operational procedures, and so on. When writing instructions, use the second person, active voice, imperative.

Again, to provide a quick refresher course in grammar:

The second person
The second person is: You. When using the second person, the (grammatical) subject of the sentence is the person being addressed. Because instructions should always be carried out by a specific person, they should be addressed to the person reading them. Specifically, you should always give instructions as if you are talking to the person carrying them out. Furthermore, you should write as though you are talking to the person as they carry out the instructions. This last point is easily identifiable where the results of the instructions are described. These should be given as if the results have just happened.

Examples:

Avoid Use Instead
The user presses the Enter key.
Result: The customer details will be displayed.
Press the Enter key.
Result: The customer details are displayed.
Active voice
For a description of the active voice, see "Descriptive writing should be in the third-person, active voice, indicative", above.
The imperative mood
The imperative mood is used to give commands or orders. Note that the subject of the sentence (You) is implied and does not need to be stated.

Examples:

Avoid Use Instead
Turning the key starts the engine. (Indicative, not imperative) Turn the key to start the engine.
The engine is started by turning the key. (Passive voice)
The operator turns the key to start the engine (Third-person, not second-person)

Use words consistently

The English language is a relatively rich one, and as any thesaurus clearly demonstrates, there are often several words or phrases that can be used to mean the same thing. Whilst variety may be the spice of life, it can hinder, rather than help, the communication process. Where possible, avoid using several words for the same purpose. Although this guideline is more applicable in international communications (see also International communication), it can be applied to all technical communications.

Examples:

Avoid Use Instead
(Within the same document or document set)

...by following the steps shown below...
...as shown below...
...by following these steps...


...by following the steps shown below...
...by following the steps shown below...
...by following the steps shown below...

Although this does not necessarily make for interesting reading, and even though you, as a creative professional, would prefer to see a bit more variety in your writing, bear in mind that you are not trying to win the Nobel prize for literature; you are trying to impart knowledge as efficiently as possible. The more consistently you use words, the faster the reader will be able to 'unload' information from your documentation.

Use words that have only one meaning

Many words in English can have multiple meanings (differentiated either by pronunciation or by context). Try to avoid using these words where it is possible to use a word with a single meaning. Specific care should be taken to avoid words that can be a noun or a verb depending on the context. If you do need to use a word that can have multiple meanings, then select the one meaning of the word that is most commonly used, and then use the word consistently to have this meaning throughout the document (or documentation set).

Examples:

Avoid Use Instead
The report lists all security breaches. Report all breaches of security to your manager. The report lists all security breaches. Inform your manager of all security breaches.

Consider also Controlled languages.

Avoid noun clusters

Examples:

Avoid Use Instead
Traffic handling optimization Optimal handling of traffic

Don't place pre-modifying nouns between a preposition and its complement

Examples:

Avoid Use Instead
Follow the steps for monitor removal. Follow the steps for the removal of the monitor.

Do not abbreviate by omitting words

It is often tempting to omit words in the interests of space. PowerPoint is particularly bad for this, as every thought or concept tends to be reduced down to a single-line bullet point. Most commonly, words such as "a" and "the" are omitted.

Although the reduced sentence may still make sense to native English speakers (assuming that the communication is in English), it is important to consider readers for whom English is not their native language. For them, having to work out the missing words will just add to the complexity of digesting the communication.

In addition, as Robert Tufte has eloquently demonstrated, the omission of words and the reduction of sentences can also have disastrous results.

Use personal pronouns

Examples:

Avoid Use Instead
It is proposed that... We propose...

Be direct

Examples:

Avoid Use Instead
Authorize the insurers to make a payment. Authorize the insurers to pay.

Manageability and digestibility

General guidelines [to be expanded]:

  • Try to use words where you don't have to understand the context before you understand the word (i.e. where a word can have several meanings - such as 'hold')
  • Use small units of information (clauses) - so that user doesn't have to hold the interpretation of a word for too long.
  • Punctuation - get it right (avoid ambiguity).
  • Try not to abbreviate where this reduces clarity of information.

Use plain language

Technical writing is a science, not an art. The purpose of technical writing is to transmit knowledge as efficiently as possible. It is unlikely that an overly-prosaic, or a deliberately mannered communication will achieve this aim more quickly than one that uses everyday language. Therefore, Technical Writers should strive to use the simplest language possible that will accurately convey the intended information. Generally, this will be the same language as would be used in a face-to-face verbal conversation.

This is not to say that you should 'write as you talk' - few of us have perfect speech (this is why we are writers and not orators!). Additionally, in face-to-face verbal conversations there are other factors that assist in the interpretation of the information - such as facial expressions, intonation, and so on. Clearly, additional care needs to be taken with written communications to ensure that the communication is clear, concise, and complete. However, it still holds true that this should be done in using simplest language possible. As a good rule of thumb, ask yourself: "Would I feel self-conscious, or affected, or even absurd, if I used this language in a conversation?" If the answer is yes, consider rewording your text.

Don't use overly-technical words when they are not needed

Often, it seems as though the authors of technical publications are more interested in demonstrating what they know (and specifically, their extensive vocabulary) than they are in imparting knowledge. Whilst this may be forgivable in an examination paper or 'set piece', there is little place for it in technical communication.

That said, it is important to use the lexicon of the intended audience of the communication (see also Defining the audience). The flip-side of this is that you should only use a specific lexicon if you are sure that your audience will understand it. For example, when writing or editing a paper for The Lancet (a highly-respected medical journal), it is acceptable (and even essential) to use medical terminology. However, when writing on the same subject for a daily newspaper, it would be better to use terms a layman would understand (although this depends on the newspaper concerned!). If you are unsure whether the audience will understand a term, you might want to consider taking the 'lowest common denominator' approach and use the most commonly-understood term. Alternatively, you might want to use the 'specialist' term, but provide a layman's explanation of the term (in a footnote, end-note, or glossary if necessary) as well.

Note that many industries have their own lexicon, and one should always use the relevant terminology when one is writing within that industry (see also Styles and standards).

Keep the vocabulary simple

Do not use more complicated expressions than necessary. Always look for the simplest way of expressing your point, and then use that. People seldom read technical documentation for entertainment - they want to extract the required information as quickly and as efficiently as possible. The simpler the language used, the better they are able do this.

Examples:

Avoid Use Instead
If you require the retrieval of a large number of records... If you need to retrieve a large number of records...

Avoid colloquialisms and slang

One should never use slang in a technical publication. There is simply no place for it. Although it is important to use the language of the audience, one must always make sure that the entire audience will understand it, and this is hard to guarantee with slang. Slang also has the disadvantage that the same word or phrase may mean different things to different people. This is also true of colloquialisms, especially where a publication is to be distributed across several regions (or even across several social groups). Although the use of 'proper' English and the avoidance of local 'flavor' may make the overall communication less 'colorful', you can at least be sure that the audience will still understand it, regardless of their regional, social or racial background. The same cannot be said for slang or colloquialisms.

Recommended books

  

See also

Personal tools
Support