Worksheet:
Style-o-Rama (tips for a polished technical writing style)
models | processes
techniques | links
resources
on i.d. business and management
home
|
Worksheet:
|
models | processes |
Looking to polish your technical writing style?
Consider these suggestions, which identify ways to tighten writing, use words with precision, and provide the appearance of complete work.
Note that suggestions are listed in alphabetical order.
| Advise, advice | Advise is the verb form. Advice is the noun form. Example: By dispensing advice (with a c), Ann Landers advises (with an s) people on ways to handle common problems. |
||||||||||||||||
| Although, while | While implies time. Only use the word when you mean to imply
a time sequence. Otherwise, use although. Correct example: Although I hadn't seen Mary, Not correct: While I hadn't seen Mary |
||||||||||||||||
| Bold face type | Primarily use for headings: chapter and section headings,
headings on tables, and headings (captions) on graphics. Avoid overusing bold type. If you use bold too frequently to catch readers' eyes, the phrases in bold will compete with one another for users' attention. They'll end up paying attention to nothing. |
||||||||||||||||
| Cont. (and other abbreviations) | Avoid abbreviations. They look sloppy. Spell out the words. | ||||||||||||||||
| Easy (and other value words) | Avoid this and other words--like simple and clear--that make
assumptions about how readers might respond to information. We use such words to pacify nervous readers, but the readers might still find passages to be difficult and unclear. When they're told that the passages should be easy, simple and clear, readers who find them otherwise feel that much more uncomfortable. By avoiding these words, you avoid the downfalls that accompany them. |
||||||||||||||||
| Easier (and other "relatives") | Terms like "easier" suggest a relationship with
something that is "harder." If you refer to something as "easier,"
then you should explain what it's easier than. Correct example: We designed the new version to be easier to use than the previous version. Note: Note that the phrase "intended to be easier;" this expression is not worded so that it assumes how users actually feel about it. Not correct: The new version is easier. (Than what?) |
||||||||||||||||
| Etc., i.e., e.g. | Avoid the word. It looks like you were lazy and didn't feel
like finishing a list or didn't know which terms to use. Instead, if you are just providing a list of examples, begin with "such as" or "for example;" it implies that you do not intend to provide a complete list. |
||||||||||||||||
| Execute | To talk about a computer program, avoid this word. It implies the execution of a prisoner. Instead, use the term "run." | ||||||||||||||||
| Generalizations | Avoid broad generalizations, unless you can substantiate
them. They call into question your credibility. Correct example: According to Redish, users of technical information read to learn or to learn to do. Not correct: Readers expect to learn in a document. (Says who?) |
||||||||||||||||
| In order to | Change to the word "to." The words "in order" are extraneous. |
||||||||||||||||
| Italic type | Only use in these instances:
Do not use italic as a means of getting users' attention--as empahsis. Research indicates that italic type is actually harder to read than regular type. The result is text gets lost on the page or screen, rather than standing out. |
||||||||||||||||
| Its, it’s | Only use the apostrophe for the contraction of it is. Correct example: It's raining cats and dogs out there. Not correct: Its raining cats and dogs out there. For the possessive form of its, do not use an apostrophe. Correct example: Check out that store. Its coat selection is great. Not correct: It's coat selection is great. |
||||||||||||||||
| ITS | Avoid using all caps. | ||||||||||||||||
| Leads | One of the toughest technical writing challenges is writing the first paragraph--or lead--to a topic. It must gain attention, and hold readers' interest. | ||||||||||||||||
| noun buildup | Even though this is a popular way to create new technical
terms, placing 3 nouns together creates reading difficulties for readers. Example: file control block Rewrite the term as a prepositional phrase. To do so, reorganize the expression using this formula:
|
||||||||||||||||
| S/he, they, user | Different ways around the awkward problem of sexist writing
(writing that prefers one gender over the other by referring to the third person singular
as either he or she). The best way to avoid this is by writing all sentences in the third person plural. Examples: Rather than use he or she, use they. Rather than saying "user" say "users" Top |
||||||||||||||||
| Since, because | Since implies time. Only use the word when you mean to imply
a time sequence. Otherwise, use because. Correct example: Because I didn't understand Not correct: Since I didn't understand |
||||||||||||||||
| There are, there is, it is | There and it are ambiguous. For example, in the phrase,
"there are 10 men at the counter," what "there" refer to? It doesn't.
Try avoid these expressions and rewrite the sentence to be more specific. Top |
||||||||||||||||
| Underscore | Avoid, except when indicating links (and this is handled
automatically by the system). Underscore type primarily came into use on typewriters, which did not have italic or bold type. The underscore served as a substitute. |
||||||||||||||||
| Utilize | Avoid 3-syllable words when 1- and 2-syllable words will do. They sound stilted and create unnecessary difficulty for readers. |
||||||||||||||||
| very, quite | Avoid these words. Although they emphasize your interest in
the point, they add no precision and little meaning. Top |
||||||||||||||||
| Which, that | Always precede which with a comma. The comma and which
indicate a restrictive clause. Otherwise, use that. Correct example: The team, which had 3 injured players, won the Super Bowl. Not correct: The team, that had 3 injured players, won the Super Bowl. | ||||||||||||||||
| Widow | A widow is when a single line of text is physically detached
from the rest of the text. Examples:
Avoid widows--the text is usually lost to the eye and ignored. Change page breaks to avoid widows. Top |
||||||||||||||||
| Will | When writing instructions, avoid this word. Either the result
happens or it doesn't. The result does not happen in the future, it happens in the present
for the person who is reading the instructions. Top |
||||||||||||||||
| You | Although current trends in style for technical communication recommend writing in the second person ( to you), make sure that "you" refers to a real person--like a reader--rather than an ambiguous being "you know…" |
models | processes | techniques | resources on i.d. business and management | home
(c) Copyright. 1999, 2000, 2001, 2002. Saul Carliner. All rights reserved.