Technical writing style

From Wikiversity

back to Technical Writing Level 1

How to edit Wiki

Wikiversity Main Page

[edit] Your Goal

Remember that your aim as a technical writer is not to impress, but to inform.

• Write clearly, using words your audience understands. Simplify your sentences. Fewer words mean more clarity. If a sentence looks long or confusing, it probably is: rewrite it. Don't be afraid to rewrite repeatedly until the meaning is clear.

• Talk directly to your reader. In general, prefer the active voice, the present tense, the second person, and the imperative mood. Also be aware, however, that there are occasions when the first person, third person, past tense, future tense, and/or declarative mood are better.

• Avoid unnecessary repetition, redundant jargon, and the passive voice.

Consider example A below as a demonstration of poor technical writing:

Imagine you are a user of the software program who wants to draw a graph using the computer software. First, the user must install the software program. Then, you can select some data with the mouse or keyboard. Then finally the user must click on the Draw button in the software program's on-screen toolbar. The computer will now hopefully draw the graph.

And here is example B, which has the same information content:

To draw a graph of the selected data, click the Draw button.

If you would enjoy transforming A into B, then you probably have what it takes to be a great technical writer.

If, on the other hand, you consider A more informative and useful than B, then perhaps another profession might be a better choice.

[edit] Important information first

By putting important information at the beginning of a sentence, we make that sentence easier to understand. It also serves to clarify what is the most important part of the sentence.

Example

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 the cliff.

[edit] Use your Audience's Vocabulary

The goal of all good User Documents is to improve the Reader's experience with the product. By using synonyms for "technical" terms, the writer makes the Reader's document searches more effective, since the needed topics will be found using the Reader's words.

Source: by Barry Millman, Ph.D.

[edit] Sentence Length

The length of a sentence is vitally important in conveying information, which is of course the primary task of the technical writer. A series of long sentences tax the brain and make remembering information difficult, while sentences that are too short sound stunted and fragmented. In short, balance is the key word when creating sentences.

The ideal sentence length for technical writing is somewhere between 15 and 20 words, and varying the length of your sentences makes for lively reading.

[edit] Too Long Sentences

Sentences that are 30 words or more can lead to confusion and a lack of clarity; thus, it is always better to split long sentences into two or more chunks, or, alternatively, you can create a list to convey this information in a clear manner.

[edit] Too Short Sentences

Don't use short sentences. They often fail to contain sufficient information. They feel too fragmented. Try merging sentences to create something understandable. Use conjunctions and semicolons. Don't fall into the trap of writing overly long sentences.

[edit] Five Rules of Concise Communication

[edit] Avoid the obvious

When you consider the audience you are writing for, there is no need to tell them to turn the server on.

[edit] Avoid padding

When reading a piece of technical writing, the audience is not looking at the style of the prose, but rather for information to perform a task, thus it is vital to avoid using padding, or filler. Phrases such as “kind of”, “sort of” and “essentially”. Filler is a perfectly acceptable spoken tool, but not for writing. Eliminating filler will also shorten your sentences.

[edit] Avoid redundant prepositional phrases

Prepositional phrases, the combination of a preposition with a noun phrase, are among the worst offenders in making text long and tiresome to read. Often it is possible to replace an entire phrase with a single word.

Examples:

use now instead of At this point in time
use suddenly instead of All of a sudden

[edit] Avoid verbosity

As has been said before, our task as technical writers is not to re-create Shakespeare but rather to provide information in a primarily functional form. Being wordy is not a virtue in technical writing, being accurate is. Why write phrases such as “on a daily basis” when “each day” will do?

[edit] Avoid pomposity

While it is good to have a wide vocabulary, a piece of technical writing is not the place for showing off your linguistic abilities. Leave the waffle to marketing, technical writing is about producing clear, plain instructions to be followed by engineers. We are not writing for the Times Literary Supplement.

A.  "The rat is eaten by the cat."

B.  "The cat eats the rat."

The file is edited by the skryx.

The skryx edits the document.

This Wiki has been written by various authors.
Mistakes were made.
One must masticate thoroughly to ensure the burrito will have been eaten completely.

Various authors wrote this Wiki.
I made a mistake.
Chew well to eat the whole burrito.

The user may choose to open his or her chosen file, and it will automatically open itself when it is hit by his or her mouse.

Click any file.  Your file opens.

1.  Click a file to open it.
2.  Select Rename from the Edit menu.
3.  Type a new file name.
4.  Click Save.

Save your file.

or

Type your address.

Hit the Open button and then write your name there. Hit Enter.

1.  Click Open.
2.  Type a name in the box.
3.  Click Save, or press Enter.

[edit] Keeping it real

It is important in our writing to maintain focus and only give information about the task in hand. It is easy to fall into the trap of hiding the real subject of a sentence and this can lead to a lack of clarity.

Example

"The use of the save function will store your information."

This is better written as:

"The save function will store your information."

Keeping our focus on the real subject of our text is one of the main reasons for shunning the passive voice. By maintaining the active voice the subject is always clear.

As well as focusing on the real subject, we must also keep focused on what is the key verb in the sentence. This is a fairly common problem in technical writing due to verbs being made into nouns and then collocated with a weak verb.

Example

"To effect the installation press run."

This is much better as follows:

"To install press run."

[edit] Correct Punctuation

Just as in a regular text, it is important to punctuate a list correctly.

If the list is made up of phrases, use lower case letters to start with, with no full-stop (period) at the end.

Example

The new Skoda Fabia has three benefits:

• greater fuel efficiency
• more head room
• more rear leg room

When the items are complete sentences then use a capital to begin with and a full-stop (period) at the end.

Example

The new Skoda Fabia has three benefits:

• The fuel efficiency is greater.
• There is more head room.
• There is increased rear leg room.

List items are sometimes an initial phrase followed by a complete sentence in which case use capital letters and full stops (periods) for the phrases as well as the complete sentences.

Words are important, they are the building blocks from which our texts are made. As such, it is vital that we use words properly and in such a way as to aid the clarity of our writing.

[edit] Subject

Our subject matter is serious, people's jobs may be on the line, therefore we write in a serious style.

Remember: Warnings always come first. If your reader's actions could cause damage to life or property, that's the first thing they must know.

[edit] Formality

Part of our task as information specialists is to write in a tone that is suitable for the audience. In writing for educated and experienced engineers an informal tone is entirely inappropriate, most technical writing uses a reasonably formal style.

When deciding the style and tone in which we write, the audience, the subject and the purpose are our main considerations.

[edit] Audience

Audience awareness dictates style. As we are writing for professionals we must write professionally, in a reasonably formal style.

[edit] Purpose

Our purpose is to inform, not to entertain. So our writing must be informational.

[edit] Simple English

Some of our audience are not native speakers of English, and for some English will not even be their second language. Thus keeping our texts as simple as possible is very important, and many industries have adopted a “Simplified English” that consists of about 1000 words, each with just one meaning. Being aware of any relevant Simplified English for the target industry will help you prepare text that the audience is likely to understand.

The use of articles in English is one of the most difficult aspects of grammar, here are the rules;

[edit] The

Articles in English are invariable. They are always the same regardless of what is being spoken about, "the" is always "the".

Usage:

1. To refer to something that has already been mentioned.

An MGC is a "Media Gateway Controller"; the MGC controls all activity on an IP phone network.

2. When both the speaker and listener know what is being talked about, even if it has not been mentioned before.

"Where is the kitchen?"

3. In sentences or clauses in which we define or identify a particular person or object:

The person who wrote the documentation has excellent style.

4. To refer to objects that we regard as unique:

the sun, the moon, the world

5. Before superlatives and ordinal numbers:

the highest building, the first page, the last chapter.

6. With adjectives, to refer to a whole group of people:

the Japanese, the old

7. With names of geographical areas and oceans:

the Atlantic, the Gobi Desert

8. With decades, or groups of years:

she grew up in the seventies

[edit] A/AN

Use 'a' with nouns that start with a consonant (letters that are not vowels), 'an' with nouns starting with a vowel (a,e,i,o,u)

Examples:

• A chair
• An apple
• A truck
• An orange
• A castle
• An opera

NOTE: "An" before an h mute - an hour. "A" before u and eu when they sound like 'you': a european, a university, a unit

The indefinite article is used:

to refer to something for the first time:

An MGC is a "Media Gateway Controller", the MGC controls all activity on an IP phone network.

with jobs:

• John is a builder.
• Sarah is training to be a doctor
• He hopes to be a footballer.

with nationalities and religions:

• Dick is an American.
• Panjet is a Sikh.

with names of days:

• I was born on a Thursday.

to refer to a kind of, or example of something:

• The server room is a noisy place.

with singular nouns, after the words 'what' and 'such':

• What a shame!
• She's such a beautiful girl.

meaning 'one', referring to a single object or person:

• I'd like a payrise please.
• The writer wrote a novel.

Notice also that we usually say a hundred, a thousand, a million.

[edit] Exceptions

When there is no article:

with names of countries (if singular)

• Germany is an important economic power.
• He's just returned from Zimbabwe.
• (But: I'm visiting The United States of America next week.)

with the names of languages

• French is spoken in Tahiti.
• English uses many words of Latin origin.
• Indonesian is a relatively new language.

with the names of meals.

• Lunch is at midday.
• Dinner is in the evening.
• Breakfast is the first meal of the day.

with people's names (if singular):

• John's coming to the party.
• George King is my uncle.
• (But: we're having lunch with the Morgans tomorrow.)

with titles and names:

• Prince Charles is Queen Elizabeth's son.
• President Kennedy was assassinated in Dallas.
• Dr. Watson was Sherlock Holmes' friend.
• (But: the Queen of England, the Pope.)

After the 's possessive case:

• His brother's car.
• Peter's house.

with professions:

• Engineering is a useful career.
• He'll probably go into medicine.

with names of shops:

• I'll get the card at Smith's.
• Can you go to Boots for me?

with years:

• 1948 was a wonderful year.
• Do you remember 1995?

With uncountable nouns:

• Rice is the main food in Asia.
• Milk is often added to tea in England.
• War is destructive.

with the names of individual mountains, lakes and islands:

• Mount McKinley is the highest mountain in Alaska.
• She lives near Lake Windermere.
• Have you visited Long Island?

with most names of towns, streets, stations and airports:

• Victoria Station is in the centre of London.
• Can you direct me to Bond Street?
• She lives in Florence.
• They're flying from Heathrow.

in some fixed expressions, for example:

• by car
• by train
• by air
• on foot
• on holiday
• on air (in broadcasting)
• at school
• at work
• at University
• in church
• in prison
• in bed

[edit] Kurt Vonnegut

Creative Writing 101 Now lend me your ears. Here is Creative Writing 101:

• Use the time of a total stranger in such a way that he or she will not feel the time was wasted.
• Give the reader at least one character he or she can root for.
• Every character should want something, even if it is only a glass of water.
• Every sentence must do one of two things—reveal character or advance the action.
• Start as close to the end as possible.
• Be a sadist. No matter how sweet and innocent your leading characters, make awful things happen to them—in order that the reader may see what they are made of.
• Write to please just one person. If you open a window and make love to the world, so to speak, your story will get pneumonia.
• Give your readers as much information as possible as soon as possible. To heck with suspense. Readers should have such complete understanding of what is going on, where and why, that they could finish the story themselves, should cockroaches eat the last few pages.

The greatest American short story writer of my generation was Flannery O’Connor (1925-1964). She broke practically every one of my rules but the first. Great writers tend to do that.

[edit] George Orwell

A scrupulous writer, in every sentence that he writes, will ask himself at least four questions, thus:

1. What am I trying to say?
2. What words will express it?
3. What image or idiom will make it clearer?
4. Is this image fresh enough to have an effect?

And he will probably ask himself two more:

1. Could I put it more shortly?
2. Have I said anything that is avoidably ugly?

One can often be in doubt about the effect of a word or a phrase, and one needs rules that one can rely on when instinct fails. I think the following rules will cover most cases:

• Never use a metaphor, simile, or other figure of speech that you are used to seeing in print.
• Never use a long word where a short one will do.
• If it is possible to cut a word out, always cut it out.
• Never use the passive where you can use the active.
• Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
• Break any of these rules sooner than say anything outright barbarous.

[edit] Naming Conventions

It is important to use the correct terminology in technical writing. Standards exist in order to prevent confusion.

[edit] Screen Terminology

Use proper terminology when referring to the user interface:

• Area
• Button
• Check box
• Close button
• Desktop
• Dialogue box
• Dropdown lists
• Expansion boxes
• Fields
• Filenames
• Folders
• Icon
• Keyboard keys
• Maximize button
• Menu and menu item
• Menu bar
• Minimize button
• Non-GUI screen
• Option button
• Paths
• Quick Launch bar
• Scroll arrow
• Scroll bar
• Scroll box
• Start button
• Submenu
• Tab
• Taskbar
• Taskbar button
• Title bar
• URL address
• Window
• Wizard page

For information on GUI (Graphical User Interface) elements not mentioned here, see Microsoft Manual of Style for Technical Publications, 3rd ed.

[edit] Names for Keyboard Keys

Spell keyboard key names as they appear on the keyboard in both text and procedures. Use all capital letters referring to specific keys. Write arrow keys in small letters when referring to them generally. When writing about a specific arrow, for example \’DOWN ARROW\’, use all capital letters.

• ALT
• ALT GR
• arrow keys
• BACKSPACE
• BREAK
• CAPS LOCK
• CLEAR
• CTRL
• DELETE
• DOWN ARROW (use with the and key)
• END
• ENTER
• ESC
• F1-F12
• HOME
• INSERT
• LEFT ARROW (use with the and key)
• NUM LOCK
• PAGE DOWN
• PAGE UP
• PAUSE
• PRINT SCREEN
• RESET
• RIGHT ARROW (use with the and key)
• SCROLL LOCK
• SELECT
• SHIFT
• SPACE BAR (use with the)
• SYS RQ
• TAB
• UP ARROW (use with the and key)

For information on keyboard key names not mentioned here, see Microsoft Manual of Style for Technical Publications, 3rd ed.

[edit] Style Manuals

Technical writing is not a case of simply creating sentences, it is about communication, more precisely it is about communicating technical information to show the reader how to do something.

Therefore, a style manual is a useful tool that we can use to make sure that our writing is acceptable and clearly understandable to the audience.

More than anything a style manual is a form of self editing.

[edit] Why use a style manual?

Technical writing, in common with other forms of writing, has, over time, developed an accepted style in which the focus is on clarity, precision and usability rather than on being the kind of text about which a literary critic would write a doctoral thesis.

We use style manuals primarily as a self-editorial tool. In a sense, style manuals are documentation for documentation and, as such, are a reference for us when we are uncertain how best to express the information we have.

We also use them as a tool to keep us "on message" and not heading off on tangents.

[edit] Example Style Manuals

MS Manual of Style

This style manual from Microsoft has become the industry standard for technical writers, especially within the software development industries, although it is also used across a range of other sectors.

The Chicago Manual of Style

This is an invaluable resource, which is available on-line at www.chicagomanualofstyle.org, and has been described as the "bible of publishing and research".

[edit] Further Reading

• Creating useful lists
• Basic Patterns and Elements of the List
• Technical Writing Style Tips
• Good Technical Writing
• Hints on Writing Style
• Technical Writing made easier
• Guidelines for Technical Writing
• Good Documentation
• Writing Clearly and Simply
• Writing Clearly and Concisely
• Common Errors in English

back to Technical Writing Level 1