Technical writing style

To meet Wikiversity's quality standards, this article may require some cleanup.Please discuss this issue on the talk page, and/or replace this tag with a more specific message. Editing help is available.

Free short videos are available from TWFred (an author of Wikiversity's Technical Writing Course) explaining technical writing strategies and techniques. These videos complement the contents of this Wikiversity course. Topics include the following:

Some business environments don't understand the technical writing style, insisting on passive voice and artificial formality. Modern technical writing directly addresses the reader in an unpretentious way.

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.

In the U.S., periods and commas usually fall inside the quotation marks. In the UK and most other countries, terminal punctuation usually goes outside the quotation marks unless part of the quotation. This style (sometimes called logical punctuation) is also permitted in American writing where precision is necessary, e.g. in presenting computer code and commands, or in textual criticism.

When reading a piece of technical writing, the audience does not benefit from elaborate prose. They just need information on how to perform a task. Avoid using padding, or filler. Don't use phrases such as, kind of, sort of, and essentially.

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.

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.

While it is good to have a wide vocabulary, technical writing is not the place for showing off linguistic abilities. Technical writing is about producing clear, plain instructions for a specific audience.

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 speak English.

Passive

B. English was 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.

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.

First, second, and third person refer to personal pronouns that reflect a point of view in singular and plural forms. Each "grammatical person" can be written in subjective case, objective case, or possessive case.

When writing or editing technical content, consider the sentence or paragraph's meaning. The two examples below demonstrate common uses of third and second person.

Plain language specifications generally specify that you use contractions where appropriate.[1] Do not use irregular contractions, or contractions that reflect future tense or passive voice—e.g., "...the motor'll start."

Commonly, steps in a procedure or task follow the navigational 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.

We interact with computers in a variety of ways. You can select anything on an application user interface by selecting 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. If there is more than one method to perform an action, use the most common method. 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.

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.

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.

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

Turn in your cycle log each Friday.

Writing for translation: Use gender-specific pronouns when writing for a language that uses personal pronouns that differ according to gender.

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

Use unordered (bulleted) lists when the audience doesn't require that the information be in any particular order, as in lists of:

Features

Options

Components

Note: Options are non-exclusive possible actions in the software.

Use ordered (numbered) lists when the audience needs the information in a particular order, or needs to refer to list items by number:

Steps of a procedure

Items on a check list

Requirements in a specification

Even lists can become overly long and require breaking up, this is best achieved by separating the information chunks as described in Technical writing structure into chunks. Most people can remember a maximum of 7 ± 2 items without too much hassle, as proposed by George Miller. Generally, however—once a list goes above 10 items, sub-divide it.

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

Example

The new Skoda Fabia has the following 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 the following 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.

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.

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.[citation needed]

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 avoid writing the uncomfortable.

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.

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 MicrosoftManual of Style for Technical Publications, 3rd ed.

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.

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.

A good style manual guides writers through the complex world of English punctuation, syntax, grammar, and other writing issues. 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 use a terminal comma: "chickens, ducks, and geese." Use the convention appropriate for the type of writing, 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.