Technical Writing Standards

Acronyms and Abbreviations

Abbreviations are shortened forms of words such as ASME for American Society of Mechanical Engineers. Acronyms are formed when the abbreviation forms a pronounceable word such as NATO for North Atlantic Treaty Organization.

Abbreviations and acronyms should be spelled out the first time they appear in a technical document with the shortened form appearing in parentheses immediately after the term. The abbreviation or acronym can then be used throughout the paper.

Example: The Society for Technical Communication (STC) is a professional association dedicated to the advancement of technical communication, content, and information management.

Common abbreviations (U.S.) or acronyms (NASA) do not need to be spelled out when first used in a document.

Ambiguity

Ambiguity occurs when words or passages can be interpreted in more than one way. Abstract language, misplaced modifiers, and vague pronoun reference can cause ambiguity. To make writing clear, avoid:

• abstract language (really, quite, severely, very)
• overusing pronouns, particularly it, these, and this
• imprecise or subjective terms (fast, slow, tall, small)
• words that have no precise meaning (bit)

Examples:

Ambiguous:

“The voltage across a forward-biased silicon diode is small."

Clear:

“The voltage across a forward-biased silicon diode is 0.7 V.”

Ambiguous:

“Because Senator Martin is less interested in the environment than in economic development, he sometimes neglects it.”

Clear:

“Because Senator Martin is less interested in the environment than in economic development, he sometimes neglects the environment.”

Ambiguous:

“I recommend you increase your margins a tad.”

Clear:

I recommend you increase your margins by 0.25 in.”

Ambiguous:

“This year’s raise is quite a bit less than last year’s raise.”

Clear:

“This year’s raise is 0.5% less than last year’s raise.”

Analogies and Metaphors

Analogies and metaphors in useful in technical writing to illustrate abstract or complicated ideas by making comparisons between two generally unlike things.

Example:

“When two atoms approach each other at great speeds, they go through one another, while at moderate speeds, they bound off each other like two billiard balls.”

Sir William Bragg

Audience

Writing with the intended audience(s) in mind is one of the most fundamental concepts of technical writing. Many technical documents will not only be read by the first person (primary audience) but may also be read by secondary audiences: readers in various levels of management, prospective financiers, or even individuals who access information without the writer’s knowledge.

For this reason, it is important to consider who may read your documents beyond the primary audience and write with any additional audiences in mind. This means targeting information appropriate for the knowledge of the audience(s) and using accessible language that both technical and non-technical audiences can understand.

Cliches

Cliches, or figures of speech, are terms that have no concrete meaning and can affect the tone and professionalism of a document. Cliches should be avoided in technical writing. Examples include:

Examples:

• water under the bridge
• writing on the wall
• easier said than done
• close the deal

Conciseness

Concise documents convey meaning using the fewest words possible without sacrificing meaning or clarity. To achieve conciseness:

• Eliminate empty/wordy phrases (there is/are and it is). These are considered to be indirect phrases and tend to be unclear and wordy. Direct statements, on the other hand, are clear and concise.

  Instead of:

  “There are 25 students who have already expressed interest in next year’s program.”

  Use:

  “Twenty-five students have already expressed interest in next year’s program.”

• Write using the active voice

  Instead of:

  “It was determined that the machine was broken by John.” (10 words)

  Use:

  “John broke the machine.” (4 words)

• Avoid using weak verbs

  Instead of:

  My recommendation is for a larger budget.

  Use:

  I recommend a larger budget.

• Eliminate filler words (very, quite, really, somewhat, that)

Contractions

Contractions are shortened forms of words with the missing letters represented by an apostrophe such as “you’ll” for “you will” or “didn’t” for “did not.” Contractions are unprofessional and informal and should be avoided in most technical documents.

Generalized Statements

Generalizations are broad statements or ideas that are applied to a group of people or things and should be avoided in technical writing. These statements are difficult to substantiate and are too broad to be supported.

Examples:

The only way to learn another language is to visit the country where it is spoken.

Cats are nicer than dogs.

Gender-Neutral Terms

Avoid specifying gender when possible. Gender specific language can create stereotypes, make generalizations, and exclude gender. Individuals should not be referred to solely as he or she. To achieve gender neutrality:

• Use generic terms when referring to specific groups of people (“supervisors”)
• Avoid gender-specific pronouns (“his” or “her”)
• Use gender-neutral titles when referring to people “(sales representatives” not “salesmen”

Examples:

• A student should always do his homework. (not gender neutral)
• A student should always do his or her homework. (gender neutral)
• Students should always do their homework. (gender neutral)
• A student should always do their homework. (gender neutral) *

*While it may seem strange or incorrect to use the plural their to refer to a single student, their has become the preferred replacement in many places in order to ensure gender neutral language. It is no longer considered grammatically incorrect to use their as a singular pronoun in this context.

Headings

In technical reports, headings are used to organize documents, guide the reader, and break content into manageable chunks of information. Readers often peruse headings and read those sections that pertain to them.

Headings organize content into large sections (major headings) and then into smaller sections (sub-headings). Headings are formatted by level (first level, second level, third level, etc.) and vary in their position and formatting. Discipline- and employer-specific style manuals will provide guidelines in the placement and visual layout of headings. Headings vary in the type of information they provide:

• Brief topic headings use short words or phrases
  

  Example:

  College Applications

• Statement headings use sentences or phrases and are more informational in nature.

  Example:

  College Application Process

• Question headings are useful when writing documents that explain how to do something.

  Example:

  How do I Apply for College?

When using headings:

• Construct headings in a parallel fashion
• Try to avoid starting headings with a, an, or the
• Aim for at least two headings at each level; avoid dividing a section into a single sub-section if possible
• Avoid repeating the wording of a higher-level heading in a sub-heading
• Use headings to create the table of contents (if applicable to the document)

Jargon

Jargon is often called professional slang and consists of terms specific to a particular organization. Examples of jargon include terms like “flame” or “FUBAR.” Jargon sets members of an organization apart from non-members. When communicating with individuals who are likely to be unfamiliar with jargon, avoid using the term.

Lists

Lists are useful in technical writing for three purposes: to write a series of related items, to describe a series of tasks, and to make items visually accessible. Lists can be written in a sentence (as in the previous sentence) or set off from the text vertically. Items listed vertically are prefaced with a bullet, number, or checkmark. Bulleted lists make items easy to see or locate, numbered lists organize steps in a process, and checklists communicate items that need are required or need to be completed.

Lists are prefaced with a lead-in phrase (Items to review for the training:) or sentence (The following topics will be reviewed at the training:)

Key points to keep in mind when creating lists:

• Lists should be constructed in a parallel fashion.
• Lists comprised of brief items typically contain no ending punctuation.
• Lists with no sequence required should be arranged logically (most to least important, alphabetical)
• Lists written as full sentences should use appropriate ending punctuation.

Narration (Point of View)

When writing, it is important to use appropriate tense and narration. Engineers often write to explain how something happened: a lab procedure, a site visit, an accident, a recommendation.

Third person narration is most often the appropriate choice in technical documents and academic journals, but in some cases it might be appropriate to use first or second person (common in business correspondence).

Examples:
First person narration, “I” words are used.
I should get good grades in college.
We should get good grades in college.

Second person narration, “You” words are used.
You should get good grades in college.

Third person narration, “he/she/neutral” words are used.
A student should get good grades in college.

Students should get good grades in college.

Objectivity

Technical documents present facts, data, evidence, calculations, results, and theories, which must be presented in an impersonal, neutral, and objective manner. Avoid use of the word “feelings” or the verb “feel” in technical writing.

Phrases such as “I feel this is the best approach” evokes emotion, is not objective, and can lend uncertainty to technical writing. Similarly, “When the weight feels right” should not be used in describing inanimate objects.

Paragraphs

Paragraphs are the building blocks of documents. It is important to keep in mind the basic elements of paragraph construction: each paragraph should contain a topic sentence that is well-developed and supported, discuss one idea, and transition to the next paragraph.

In technical writing, paragraphs are generally kept to 4-6 lines. Short paragraphs emphasize main ideas, encourage conciseness, keep the reader’s attention, and break up content into manageable chunks.

Parallelism

Parallelism means using the same structure for listed items. These items can occur in a sentence, in a table, in a bulleted or numbered list, or in headings. Sentences with parallel structure are easier to read and flow more smoothly.

Not Parallel:

“In heat and mass transfer class, students learned about modelling heat equations, dimensioning for thermal design, and how to analyze results.”

Parallel:

“In heat and mass transfer class, students learned about modelling heat equations, dimensioning for thermal design, and analyzing results.”

When creating a bullet list, all items in the list should be parallel in construction.

Redundancy

Redundancy means using two or more words that essentially mean the same thing. Redundancy affects conciseness.

SI versus Customary Units

Systeme Internationale (SI) units are the most widely and officially recognized system of metric units for weights, dimensions, and other physical measures in technical writing. Technical documents should use SI units in text, figures, tables, and equations.

Sentence Length

In technical writing, uncomplicated sentences are used to state complex ideas. Long, complex sentences tend to confuse readers. Strive for a sentence length of 10-20 words. A document should not be constructed, however, of short, choppy sentences. Varying sentence length can encourage readability, make comparisons, and contrast information.

Technical Terms and Definitions

When introducing a technical term in a document, italicize and provide a brief explanation of the term the first time it is used. There are generally three types of technical definitions: informal, formal, and expanded.

Informal definitions contain a word or brief phrase, often in parentheses, that gives minimal information about the term.

Formal definitions are typically a full sentence that distinguishes the term from other similar terms and includes the term itself, a class to which the term belongs, and distinguishing feature(s) of the term, which typically describe what the term does.

If the technical term has unclear or multiple meanings, add a qualifier to the beginning of the definition.

Tone

Tone refers to the feeling or attitude a document evokes; tone can also portray how the writer feels about a subject. Tone can be dependent on the purpose, audience, or medium of the message. Strive for neutral, professional, understandable words. Because engineers deal with complex information and terminology, word usage should be accessible and familiar.

Voice (Active or Passive)

Voice refers to how verbs are used in sentences. Although passive voice has long been a hallmark of technical writing, writing in the active voice is a preferred practice. Active voice makes documents more readable by making sentences more clear and concise. Passive voice is still used for certain types of technical documents such as lab reports.

When the verb is in the active voice, the subject performs the action; when the verb is used in the passive voice, the subject receives the action.

Examples:

Active:

The boy hit the ball.

Passive:

The ball was hit by the boy.

Hint: Watch for phrasing patterns common to passive voice: “was (verb)ed by….”

Use active voice when:

• writing most technical documents.
• writing needs to be concise, clear, and direct.
• it is important to know the “doer” of the sentence.

Use passive voice when:

• the genre (format) calls for passive voice (lab reports)
• the action itself is more important than who or what performed the action or when the doer of the action is unknown.

Word Choice

Words should be used that are accessible and familiar to your audiences, both primary and secondary. This means using a shorter, more well-known word in place of a longer, less-known word with the same meaning.

Examples: