Information on Technical Communication

 Reader Analysis
 Formal Report
 Analytical Report
 Typography Hints
 Instruction Basics
 Memo Format
 Oral Report
 Progress Reports
 Letter of Application
 Simple HTML

Guidelines for Revision

This page deals with revising, not writing. If you have already written a document with appropriate content and a clear sense of the audience and context, this page will show you how to revise that document’s design, sequence of presentation, paragraph and sentence style. It will also show you how to proofread the document. Revision guides for specific documents are located on the pages that describe those documents.

General Guidance for Levels of Editing

  • Document Design

  • Sequence of Argument

  • Paragraph Unity

  • Sentence Clarity

  • Common Grammar Problems

General Guidelines on Document Design

What follows are design guidelines that apply to all documents. The special design rules for specific kinds of documents are included with the descriptions of those documents.

  • Make the design of your document consistent with others produced in your organization. Use the same type font and type size, spacing, margins, document divisions, graphics placement, and vocabulary.

  • Make your document internally consistent. For example, if section one begins with a centered, boldfaced heading, ensure that all other sections begin with centered, boldfaced headings.

  • Where appropriate, use lists, not paragraphed prose, to present parallel elements of information.

  • Where appropriate, depend on graphics rather than prose for description.

  • Use paragraphed prose to argue or explain.

  • Use 12 or 14 point type in a common type face like Times, Times New Roman, Courier, or New York.

  • Avoid use of ALL CAPS.

  • In most cases, use 1" margins on the top and sides of an 8 1/2 by 11 page; readers will accept variation in the size of bottom margins.

  • Double-space multi-page documents.

  • Do not right-justify word processed documents.

Sequence of Argument:

  • Present a single, clear point.

    A unified document makes a single point, and until your readers understand that point, they cannot evaluate your document.

    So make the point early in the document; explain it in a way your readers will understand, and show them why it is significant to them.

  • Forecast your argument

    Show your readers in advance what the key elements of your document are and how they relate to each other and to your point.

    Tell your reader how many categories you will use, the order in which you will use it, and how they connect to each other. Do this for the document as a whole and for each major section. If your readers know what you are trying to accomplish, they can follow you more easily.

  • Summarize each major subdivision after completing it.

    Most skilled readers mentally summarize each section of your text after reading them. This is how such readers decide what the section means, what is significant about it, and what they are to carry from it into their further reading of your document.

    By providing a summary for them, you give them a chance to compare what they thought you meant with what you thought you meant. If they do not understand or do not agree with you, they can reread the section and resolve their confusion.

  • Define the role of your readers.

    To read your document effectively, readers need to know what you want them to do after they have read it.

    Make certain that your readers know whether you want them to act, to be prepared to be acted on, or observe a transaction among others. Thus you should avoid sentences like: "Test results will be sent on Friday." and instead write: "I will send you the test results on Friday."

  • Keep the same set of actors throughout the document.

    Do not change from "I" to "we" to "one" unless the changes are dictated by the content. If you intend to address the readers as "you," or yourself as "I," do so from the beginning of the document.

    Decide on your key terms and use them consistently throughout the document; never replace them by synonyms.

    If you are talking about stress fractures in aircraft wings, always use the phrase "stress fractures." Never call them "cracks," or "problems," or "failures."

  • Use concrete terms to help your readers to visualize what you tell them.

    Many readers understand by visualizing. You can help them to do this by using words that present a picture. For example, when you write about a wrench, write "wrench," not "tool." Everybody can visualize a wrench; nobody can visualize a tool. Whenever possible, avoid abstract terms like "concept," "aspect," "mode," and "system" that can confuse readers.

  • Identify any person, place, organization, or object that your readers will not recognize immediately.

    Use concrete terms where you can, and use any of the following techniques to clarify further.

    (1) Supplement the term where necessary with descriptive adjectives and phrases, for example: "A fax modem card, a compete fax machine installed inside the computer, . . ."

    (2) Explain or identify using information the readers already have,

    for example. "Building # 26, the one story building between the powerhouse and the fence . . ."

    (3) Supplement your document with an identifying method

    for example: "This quarterly injury report identifies locations by building number. The plant map bound in the front of the report shows the location of each numbered building."

  • Do not overidentify.

    Readers use identifying terms and phrases to visualize objects and distinguish them from each other, and readers assume that you intend them to use every term and phrase. For example: if you refer to a nut as a "5/16 stainless steel hex nut," readers assume that they will be asked to distinguish that nut from a 1/4 stainless steel hex nut or a 5/16 brass hex nut. If you do not want them to do that, omit the unneeded information. And unless you know your readers can visualize a hex nut, either describe a hex nut or call the object a "nut."