general conventions of technical style four principles and twenty concepts

GENERAL CONVENTIONS OF TECHNICAL STYLE

FOUR PRINCIPLES AND TWENTY CONCEPTS

Adapted from Pattow and Wresch,

Communicating Technical Information (2ed), 1998.

TECHNICAL WRITING

INFORMATION PRESENTATION

AUDIENCE

FACTUALFACTUAL

OBJECTIVEOBJECTIVE

SPECIFICSPECIFIC

Fundamental Considerations:

PRINCIPLE ONE:

INVOLVE READERS.

INVOLVING READERS

MORE LIKELY TO READ, UNDERSTAND,

& RESPOND

The student should take… You should take… Take...

1. ADDRESS READERS DIRECTLY

INVOLVING READERS

CLEAR & DIRECT:

EMPHASIS ON SUBJECT PERFORMING ACTION,

NOT OBJECT OF ACTION

The microscope slide should be washed… Biology students should wash the

microscope slide...

2. USE ACTIVE VOICE

In using active voice:

RULE OF THUMB:Avoid linking verb

constructions.

EXCEPTION

TO RULE:

Use passive voice in special cases to describe events in exact terms;

i.e., materials/methods sections of scientific reports.

“Fly thoraces were homogenized…”

Emphasis on action takenWhy?

INVOLVING READERS

chairman chair mailman mail carrier manpower work force workmanship work his prostate the prostate her pregnancy the pregnancy

3. AVOID SEXIST or EXCLUSIVE LANGUAGE

PRINCIPLE TWO:

SELECT WORDS CAREFULLY.

SELECTING WORDS CAREFULLY

4. AVOID INFLATED LANGUAGE

I’ve been stretching my

mouth to let those big words come

right out…

SELECTING WORDS CAREFULLY

assistance help constitutes makes necessitate require approximately about cease stop originates begins terminate end comprises makes up**

4. AVOID INFLATED LANGUAGE

SELECTING WORDS CAREFULLY

4. AVOID INFLATED LANGUAGE

Verb Corollary 1:Don’t confuse phrasal verbs with “deflated” language.

“makes up”[VERB —PARTICLE (adverb or preposition)]

WHY? Because particles are idiomatic.

SELECTING WORDS CAREFULLY

4. AVOID INFLATED LANGUAGE

“drop off”

The hill dropped off near the river.

While doing his homework, he dropped off.

Please drop this off at the post office.

Dude, did you make the drop off?

Idiomatic Accurate

SELECTING WORDS CAREFULLY

4. AVOID INFLATED LANGUAGE

Verb Corollary 2:Don’t use abstract nouns in the place of action verbs.

Centrifugation of the sample was accomplished by… The sample was centrifuged...

COMMON INDICATORS OF NEARBY ACTION VERBS HIDDEN AS NOUNS

accomplished, achieved, attained, conducted, effected, facilitated, indicated, obtained, performed, proceeded, required

SELECTING WORDS CAREFULLY

4. AVOID INFLATED LANGUAGE

Verb Corollary 3:

Avoid linking verb constructions.

Use passive voice in special cases to describe events in

exact terms;

i.e., materials or methods sections of scientific reports.

“Fly thoraces were homogenized…”

EXCEPT

SELECTING WORDS CAREFULLY

4. AVOID INFLATED LANGUAGE

In general:

Use the simpler of alternative words, but

maintain accuracymaintain accuracy of writing at all costs!

SELECTING WORDS CAREFULLY

SPECIALIZED WORDS USED OUTSIDE SPECIALTY

BUG / VIRUS / WORM TO BIOLOGISTS

BUG / VIRUS / WORM TO COMPUTER SCIENTISTS

POT TO CRIMINOLOGISTS

POT TO ELECTROCHEMISTS

GOD TO SOCIOLOGISTS

GOD TO MOLECULAR BIOLOGISTS

PCR TO PSYCHOLOGISTS

5. AVOID JARGON

SELECTING WORDS CAREFULLY

The defective gene was discovered by positional cloning--that is, by localizing its position on a particular chromosome.

The unknown chemical was identified by mass spectrometry, a technique in which a substance is ionized and fractionated by a strong magnetic field.

6. DEFINE/EXPLAIN TECHNICAL TERMSWHEN NECESSARY

SELECTING WORDS CAREFULLY

The sample was filtered before centrifugation to avoid the hassle of contamination.

…to avoid contamination.

The results suck. The results are inconclusive.

The results suck big time. The experiment must be repeated.

7. AVOID SLANG

SELECTING WORDS CAREFULLY

SHOULD BE ACCURATE AND CLEAR.

hammer vs. mallet. vs. gavel

claw vs. pincer vs. cheliped vs. gnathopod

gene vs. protein

8. USE CORRECT WORDS

SELECTING WORDS CAREFULLY

“in one ear and out the other”

AND AVOID RENOVATING CLICHES:

“in one ventricle and out the other”

9. AVOID CLICHES

PRINCIPLE THREE:

WRITE CLEAR SENTENCES.

WRITING CLEAR SENTENCES

a majority of most at the conclusion of after based on the fact that because due to the fact that because owing to the fact that because As can be seen in Fig. 1,… Fig. 1 shows… It is of interest to note that omit

10. ELIMINATE EXTRA WORDS

WRITING CLEAR SENTENCES

on a daily basis daily daily during the course of during few in number few results so far obtained results never at any time never consensus of opinion consensus

11. AVOID REDUNDANCY

WRITING CLEAR SENTENCES

Employees are entitled to two weeks of vacation with pay any time during the calendar year in which their first employment anniversary falls, three weeks of vacation with pay…

Employees are entitled to two weeks of paid vacation any time during the calendar year in which their first employment anniversary falls. They are entitled to three weeks of paid vacation…

12. WRITE SHORT SENTENCES (<25 WORDS)

WRITING CLEAR SENTENCES

Dogs stink, and their odors can be controlled.vs.

Although dogs stink, their odors can be controlled.vs.

Though their odors can be controlled, dogs stink.

13. MAKE SURE RELATIONSHIPS BETWEEN IDEAS ARE CLEAR

DOGS AND DOG ODORS

WRITING CLEAR SENTENCES

not until only when not unless only if not prevent permit not reject accept not disagree agree not illegal illegal not fail succeed

14. REWRITE NEGATIVE SENTENCES AS POSITIVES

avoid inflated language

use simple words

WRITING CLEAR SENTENCES

We purified the sodium salt of deoxyribose nucleic acid…

We purified the sodium salt of DNA… We purified sodium DNA…

15. AVOID NOUN STRINGS

We purified the deoxyribose nucleic acid sodium salt…

WRITING CLEAR SENTENCES

16. UNTANGLE CONFUSING SENTENCES (1-2 IDEAS)

Idea one Idea two Idea three and , not .

.Idea twoIdea one and Idea three .

.

(1) Idea one (2) Idea two (3) Idea three , and ,

IF NECESSARY, USE A SERIES:

PRINCIPLE FOUR:

CREATE NAVIGABLE DOCUMENTS.

CREATING NAVIGABLE DOCUMENTS

READER SHOULD NEVER HAVE TO SEARCH !!

When writing: Think of map reading.

Think of speed reading.Think of studying from a textbook.

Place important information in readily distinguishable places in sentences. Place important sentences in readily distinguishable places in paragraphs. Place important paragraphs in readily distinguishable places in documents.

17. PUT IMPORTANT INFORMATION WHERE READERS EXPECT TO FIND IT

CREATING NAVIGABLE DOCUMENTS

Corollary 1:Topics or important information are typically placed first in a sentence,

last in a sentence, or typographically distinguished* from other information.

The most prevalent cause of deaf-blindness is Usher syndrome. Usher syndrome is the most prevalent cause of deaf-blindness. Among the causes of deaf-blindness, Usher syndrome is the

most prevalent.

17. PUT IMPORTANT INFORMATION WHERE READERS EXPECT TO FIND IT

*Do not overuse italic or bold typography*Italic and Bold typically used to alert reader to nearby definition.

CREATING NAVIGABLE DOCUMENTS

Corollary 2: Avoid naked pronouns. Always follow pronouns with their antecedents. Use pronouns as adjectives only.

17. PUT IMPORTANT INFORMATION WHERE READERS EXPECT TO FIND IT

Usher syndrome involves deafness. This affects populations worldwide.

Usher syndrome involves deafness. This disease affects populations worldwide.

CREATING NAVIGABLE DOCUMENTS

DIRECT THE READER BETWEEN IDEAS.

IN THE SAME DIRECTION:

In addition,… Also,…

IN THE OPPOSITE DIRECTION:

However,… Although…, On the contrary,…

TOWARD THE END:

Finally,… In conclusion,…

18. USE HELPFUL TRANSITIONS

CREATING NAVIGABLE DOCUMENTS

19. USE LISTS* TO PRESENT MULTIPLE ITEMS

A BULLET LIST

Genealogical research of the Usher syndrome population has established that most affected families

• are descendants of Acadian ancestors

• are related to families in the three-parish study region

•are part of a large kindred descending from two emigrant French couples who arrived in Acadia in 1636

A TEXTUAL LIST

Genealogical research of the Usher syndrome population has established that most affected families (1) are descendants of Acadian ancestors, (2) are related to families in the three-parish study region, and (3) are part of a large kindred descending from two emigrant French couples who arrived in Acadia in 1636.

*Remember parallelism.

CREATING NAVIGABLE DOCUMENTS

19. USE LISTS TO PRESENT MULTIPLE ITEMS

Employees are entitled to two weeks of vacation with pay any time during the calendar year in which their first employment anniversary falls, three weeks of vacation with pay…

Employees are entitled to two weeks of paid vacation any time during the calendar year in which their first employment anniversary falls. They are entitled to three weeks of paid vacation…

Employees are entitled to (1) two weeks of paid vacation any time during the calendar year in which their first employment anniversary falls, (2) three weeks of paid vacation…

CREATING NAVIGABLE DOCUMENTS

BREAKS DOCUMENT INTO MANAGEABLE CHUCKS DIRECTS READER ALLOWS READER TO FOCUS ON IMPORTANT

MATERIAL

20. USE INFORMATIVE HEADINGS

Where to begin when describing something new?

create list of accurate and useful words

(nouns, adjectives, AND verbs)

find a logical focal point, and write outward from there, using it as a reference as necessary

organize flow