Technical writing style

back to Technical Writing Level 1

How to edit Wiki ~ Participating Author: Susan F.

Wikiversity Main Page

Goals

• Inform (Educate) the user.

• Write clearly, using words the audience understands.

• Compose simple, active voice sentences.

• Understand the audience and speak directly to the reader.

• Use active voice, third person, present tense, and the imperative mood.

• Determine if the text requires a change in grammatical person or past tense, future tense, and/or declarative mood.

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

• Evaluate your writing: write, review, and repeat.

Important information first

Important information at the beginning of a sentence makes it easier to understand.

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.

Use your audience's vocabulary

Good technical writing improves the reading experience. Use synonyms for "technical" terms to make the reader's document search more effective.

Source: by Barry Millman, Ph.D.

Understand your environment

On occasion, you may run across a business environment that does not completely understand the technical writing style. For example, you may have a manager who maintains that 'good writing' requires second person and passive voice. Third person is preferable in most technical writing. Write as if speaking to the person who will read the document. It's fine to use the pronoun, "you," but avoid overuse. You can imply second person without repeating "you" throughout the document.

Consider "Start the engine." instead of "Start your engine."

Sentence structure

Good sentence structure helps convey information. Try to keep the most important information towards the beginning of the sentence.

No

Furthermore, large volumes of water are also required for the process of extraction.

Yes

Extraction also requires large volumes of water.

Long sentences

Long sentences tax the brain and make remembering information difficult. Strive to keep sentences under 16 words. Split long sentences into two or more chunks. A sentence that lists three or more items may work better as a bulleted list.

Short sentences

The most basic sentence is a simple sentence with only one clause. Evaluate each sentence to ensure it contains sufficient information.

Quotation marks

In the U.S., periods and commas always fall inside the quotation marks. In the UK and some other countries, terminal punctuation usually goes outside the quotation marks unless it is part of the quotation.

Five rules of concise communication

Avoid the obvious

Understand the audience's technical level and know what terms you can assume they know and what terms you must define.

Avoid padding

When reading a piece of technical writing, the audience is not looking at the style of the prose, but rather for information on how to perform a task; thus, it is vital to avoid using padding, or filler. Don't use phrases such as, kind of, sort of, and essentially.

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.

Use now instead of At this point in time.

Use suddenly instead of All of the sudden.

Avoid verbosity

Write short, succinct sentences. Never say, "...as has been said before," "..each and every," "...point in time," etc. Avoid "...in order to," especially at the beginning of sentences. Every word must contribute meaning to the sentence. Technical writing is information delivery.

Avoid pomposity

While it is good to have a wide vocabulary, 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 for a specific audience. We are not writing for the Times Literary Supplement.

Technical Writing at Wikiversity Write clearly |George Orwell's general writing rules work for technical writing: 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 works. If it is possible to cut a word out, do so. Never use the passive [voice], use active instead. 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. Exceptions for technical writing: If the audience habitually uses a particular metaphor, simile, or other figure of speech, you can use it too. If scientific jargon is a standard, ensure you follow it. Once you explain a word or term, you have made it usable in that document as a technical term—so use it consistently for that element. Look at the Basic English ordered word list. Use active voice Active voice clearly shows the actor in a situation. When we read active voice, we know who does what to whom. Active voice is shorter and more interesting to read. Active voice is the standard for technical writing. Active A. They spoke English. Passive B. English was spoken. Active A. They had spoken English. Passive B. English had been spoken. Passive voice obscures the actor—sometimes deliberately, as in, "Mistakes were made." Passive voice is ambiguous and often leaves out important information. Who made those mistakes? Passive The file is edited by the administrator. Active The administrator edits the file. You can identify the passive voice easily. Sentences that have the word "by" are almost always passive. Past-participle verbs—"was eaten," "is driven"—are usually passive. You can always rework a passive sentence to turn it active. Often, you just put the actor first. Passive This Wiki has been written by various authors. Mistakes were made. One must masticate thoroughly to ensure the burrito will have been eaten completely. Active Various authors wrote this Wiki. I made a mistake. Chew the burrito well. Computer novices find it particularly irritating when they run into a sentence they don't understand. Often, these sentences are twisted relics of passive writing. Active voice adds clarity and saves readers unnecessary pain. Common intransitive verbs The following verbs cannot be used in passive voice: appear, arrive, come, cry, die, go, happen, occur, rain, sleep, stay, walk. Understanding present tense Computers have no past, and no future. Everything happens in the present as a direct result of some event, usually caused by the user. As each event takes place, the computer has a reaction. Each of these events happen in the present, so good technical writing uses the present tense almost exclusively. Cause Effect The user clicks Save. The computer saves the file. The user types a login and password. The computer checks the login and password against an authorized user list. If the login and password are on the list, the welcome screen appears. If the login or password does not match, the try again screen appears. Grammatical person Modern technical writing strongly favors third person. First, second, and third person refer to personal pronouns that reflect a point of view in singular and plural forms. Third person is common in academic writing. Each "grammatical person" can be written in subjective case, objective case, or possessive case. The second person point of view addresses a reader or listener directly and is commonly utilized in Training. For example, a script written for speaker in an E-Learning document is written in second person. Here is an example of the imperative mood and the pronoun your: Turn in your cycle log each Friday. Shorten sentences Readers process and understand short, active voice sentences. No Workers should tighten the chuck with great care because incorrect tightening may result in damage to the drill bit. Yes Tighten the chuck correctly to avoid damaging the drill bit. Avoid ambiguous sentences Do not write sentences that the reader may interpret in more than one way. No The user may choose to open the chosen file, and it will automatically open itself when it is hit by the mouse. Yes Click any file to open it. Write for application consistency Commonly, steps in a procedure or task follow the navigation structure of the application left to right, top-down. Each step must include the menu commands, or dialog box and field names in the sentence. The top-down method determines the "big picture" (global view) of the application first and then defines its features in detail. Note, based on the language we may read right to left. No Select Rename from the Edit menu. Yes On the Edit menu, select Rename. Action verbs, menus, and commands We interact with computers in a variety of ways. You can select anything on an application user interface by highlighting it using a keyboard or mouse. It is important to use action verbs and software terminology correctly. The most frequent verbs used in software are: Click Double-click Select Type Press Use of an action verb in a sentence (bolded words): 1. In the dialog box, click Open. 2. Type a name in the text box. 3. On the keyboard press Enter. Use of menu actions and commands in a sentence: 1. On the File menu, click Open. 2. Type a name in the User Name field. 3. In the Open dialog box, click Save. 4. On the computer keyboard, press Enter. Make users aware of where they are in the application. Define "what, where, and how" in each step of the task or procedure. Describe menu items for the current task left to right, top-down. Use singular possessive pronouns When referring to files, we can use the "your file;" however, this usage is informal. If there is more than one method to save a file, use the most common method. Example: No In the Open File dialog box, select your file. Yes In the Open File dialog, select any file.

Specifying gender

In the past, many writers in English used the male singular pronoun to refer to a single person of unspecified gender. This use became unpopular in the 1970s because of its association with discrimination against women.

Example (using male singular)

I saw someone in the distance. I could not see if he was male or female, but his coat was definitely brown.

Example (using gender-neutral)

I saw someone in the distance. I could not see if they were male or female, but their coat was definitely brown.

English provides no dedicated pronoun for the gender-neutral third-person singular. The word "it" refers to animals or inanimate objects. Writers often use the gender-ambiguous plural pronouns: "they," them," and "their," to describe individuals of unknown gender. This use has been recorded since at least the seventeenth century and is correct per the Chicago Manual of Style and other references. Nonetheless, it may disturb some readers so, when possible, use another solution.

In technical writing, the gender-neutral pronouns, they, them, or their, are preferable to the verbose he or she/his or her/him or her. If a sentence seems awkward, try to avoid the issue: leave out the pronoun or use second person imperative. These examples assume the operator is the audience:

Bad

The operator must turn in his or her cycle log each Friday.

Better

The operator must turn in their cycle log each Friday.

Better still

The operator must turn in a cycle log each Friday.

Writing for translation: Use gender-specific pronouns when writing for a language where personal pronouns have different forms according to gender.

Technical Writing at Wikiversity Lists How long can a list be? Most people can associate between five and nine data items together. Therefore keep your lists short. If any list of instructions has more than seven steps, you should try to break it into two or more groups, with an intermediate state between. Again, there is no iron rule. Do what is reasonable in your circumstance. Lists are a useful tool in technical writing, as they break-up overly long sentences into information chunks that are easier to digest than long-winded monologues. Why use lists? Lists are useful because they: break up long sentences create easy to digest information chunks Creating lists Use bullets or numbered lists. Use bullets when: No specific order is needed Showing off features Listing options Note: Options are non-exclusive possible actions in the software. Use number lists when: The order is important List alternatives Make recommendations Note: Alternatives are exclusive choices, which block other alternatives in the software. Even lists can become overly long and require breaking up, this is best achieved by separating the information chunks Technical_writing_structure into like chunks. Most people can remember a maximum of 7 ± 2 items without too much hassle, as proposed by George Miller. However, once a list goes above 10 items it is necessary to sub-divide the list. Example Shopping List Yogurt Bread Tea Milk Biscuits Crisps Pork chops Chicken Cheddar Chocolate Dairy Yogurt Cheddar Milk Meat Chicken Pork Chops Snacks Chocolate Biscuits Crisps Drinks Tea

Punctuation

Just as in a regular text, it is important to punctuate lists correctly. If the list is made up of phrases, capitalize the first word, do not end each list item with a comma or full-stops (periods).

Example

The new Skoda Fabia has three benefits:

• Greater fuel efficiency
• Expanded head room
• Expanded rear leg room

When items are complete sentences, begin with a capital and end with a period.

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 that case, use capital letters and full stops (periods) for the phrases as well as the complete sentences.

Subject

Subject matter is important. Remember that warnings come first. Apply warnings to any documentation that includes a task or procedure that causes damage to life or property.

Formality

Part of our task as information specialists is to write in a tone suitable for the audience. In writing for educated and experienced engineers, an informal tone is inappropriate. Most technical writing requires a reasonably formal style. When deciding on style and tone, audience, subject, and purpose are the main considerations.

Audience

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

Purpose

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

Technical Writing at Wikiversity Clarity Seven guidelines for clear writing. Use active voice Active voice works better than passive in technical writing because it focuses sentences on the person or other entity that performs the action—the agent, or actor. For clarity, active voice is vastly preferable to passive, though occasional situations make passive voice unavoidable. Be specific Use precise words as opposed to more general variants. Provide enough detail to inform the reader. Avoid ambiguity. Many words in English have multiple meanings; make it clear which meaning you intend. Eliminate useless jargon "Jargon" is a field's specialist vocabulary. Computer scientists speak of a "network" and mean something different from when a sociologist talks about a "network." Jargon is a necessary part of modern life, but we must be aware of what jargon the reader knows and how they use it. Be positive Avoid phrases that contain negative elements like "no" or "not." For example, "impossible" is a positive construction as opposed to "not possible." The main reason for using positive constructions is that the reader more readily understands information in this form. Avoid long noun constructions English commonly uses a noun as an adjective, which can cause unwieldy phrases. Often, you can clarify this with a hyphen between, for example, two nouns used as adjectives (as in the phrase "flat-bed plotter"). Clarity demands that we must write to make the meaning clear. Don't use cliches Cliches are outdated ways of writing that often represent a writer's attempt to impress. Good writing is original and clear. The best English is plain English. Don't use euphemisms Say exactly what it is you want to say, don't run away from writing the uncomfortable.

Simple English

When writing for audiences that include non-native English speakers, it is important to write simple, straightforward sentences and avoid colloquialisms. Some industries have adopted a “Simplified English” that consists of about 1000 words, each with a single meaning. Be aware of any relevant simplified English for the target industry, so you can write text that the audience can understand.

Articles

Articles in English present some of the most difficult aspects of grammar. Here are the rules.

The

Articles in English are invariable. They have one form regardless of the subject: "the" is always "the," and refers to:

• Something already mentioned: An MGC is a "Media Gateway Controller"; the MGC controls all activity on an IP phone network.
• Something both speaker and listener understand, even if not previously mentioned: "Where is the kitchen?"
• A particular person or object: The person who wrote the documentation has excellent style...
• Unique objects: the sun, the moon, the world...
• Superlatives and ordinal numbers: The best, the first...
• With adjectives, to refer to a whole group of people: the Japanese, the old...
• Geographical areas and oceans: the Atlantic, the Gobi Desert...
• Decades, or groups of years: the Seventies, the early 19th century...

A/an

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

• A chair
• An apple
• A truck
• An orange
• A castle
• An opera
• A historical (an historical is archaic and incorrect at least in the U.S.)

NOTE

An before a silent h: an hour...

A before u and eu when they make a consonant Y (sound like 'you')

a European, a university, a unit

The indefinite article:

refers 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.

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

Technical Writing at Wikiversity British or American English? There are minor differences in American and British English. For example: Spelling differences—color vs. colour; realize vs. realise Americans put periods and commas inside quotes, British outside—The sign said, "push." vs. The sign said "push". In the US, ground floor and first floor both mean the floor at street level; in Britain, the first floor is the floor above the ground floor—which Americans call the second floor. Screen terminology Use consistent terminology when you refer 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 The Microsoft Manual of Style for Technical Publications, 3rd ed. provides good recommendations for graphical user interface (GUI) terms. 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.

Dictionaries, thesauruses and grammar checkers

A part of the skill of writing is the use of dictionaries, thesauruses, and grammar checkers. For best results, use them often and in the formal writing setting. This alleviates words in passive voice, repetitive usage, and spelling errors.

Style manuals

A style manual helps writers adhere to evolved rules and conventions. In the U.S., writers use style guides from academic institutions, professional organizations, and corporations. The major style guides, however, are the Associated Press Stylebook and the Chicago Manual of Style (CMS). Generally speaking, journalists use the AP Stylebook and most other writers CMS, unless their work requires the style guide of a particular institution or corporation. The Microsoft Manual of style began as Microsoft's corporate style guide but enjoys wide use by technical writers for computer-specific issues.

Why use a style manual?

A good style manual guides writers through the complex world of English punctuation, syntax, grammar, and other writing issues. Note that these guides educate the reader in Third person, which is the preferred style. In some cases, style manuals disagree on minor points. For example, journalists, who follow the AP Stylebook, do not usually use a terminal comma: "chickens, ducks and geese." Outside journalism, writers who follow CMS do use a terminal comma: "chickens, ducks, and geese." Use the convention appropriate for the type of writing you do, but even more importantly, use the same convention all the way through the document or project. A style manual provides a basis for applying rules and conventions consistently.

The Chicago Manual of Style

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

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

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.

Further reading

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

back to Technical Writing Level 1