Online Technical Documents

Markel, M. (2015). Technical communication (11th ed.).  Boston, MA: Bedford/St. Martin's.

Chapter 7: Organizing your Information

DURING THE PLANNING PHASE of your writing process, you need to organize the information that will go into a document. Writers draw on a number of structures, or organizational patterns, to deliver information to their audiences. But how do you know which organizational patterns will work best for a given project? is it a question of the information you want to communicate? the audience you are addressing? the purpose you are trying to achieve? the culture in your own company? short answer: to varying degrees, all of these factors will influence the pattern you choose. to get some ideas, talk with experienced co- workers, study other similar documents, and read this chapter.

At this point, you should know for whom you are writing and why, and you should have completed most of your research. now it is time to start organizing the information that will make up the body of your document, whether it is a print document or an online one.

understanding three Principles for organizing technical information

In organizing your information, analyze your audience and purpose, use con- ventional patterns of organization, and display your organizational pattern prominently.

As with any important writing task, you might want to discuss your ideas about how to organize the document with others in your network. They might identify other factors that you should consider or suggest other pat- terns of organization that might work better for your audience, purpose, and subject.

analyzIng yOUr aUdIenCe and PUrPOse

Although you thought about your audience and purpose as you planned and researched your subject, your analyses of audience and purpose are likely to change as you continue. Therefore, it is useful to review your initial assess- ment of audience and purpose before you proceed.

Will your audience like the message you will present? If so, announce your main point early in the document. If not, consider a pattern that presentsyour important evidence before your main point. Is your audience used to seeing a particular pattern in the application (the kind of document you will be writing)? If they are, you will probably want to use that pattern, unless you have a good reason to use a different one.

What is your purpose in writing the document? Do you want your audi- ence to understand a body of information or to accept a point of view and perhaps act on it? One purpose might call for a brief report without any appendixes; the other might require a detailed report, complete with appendixes.

If you are addressing people from other cultures, remember that organiza- tional patterns can vary from culture to culture. If you can, study documents written by people from the culture you are addressing to see whether they favor an organizational pattern different from the one you are considering. As you do so, ask yourself the following four questions:

• does the document follow expected organizational patterns? For example, this chapter discusses the general-to-specific pattern. Does the document you are studying present the specific information first?

• do the introduction and conclusion present the kind of information you would expect? In the United States, main findings are often presented in the introduction; in some other cultures, the main findings are not presented until late in the document.

• does the document appear to be organized linearly? Is the main idea presented first in a topic sentence or thesis statement? Does supporting information follow? In some cultures, main ideas are withheld until the end of the paragraph or document.

• does the document use headings? If so, does it use more than one level?

If documents from the culture you plan to address are organized very differently from those you’re used to seeing, take extra steps to ensure that you don’t distract readers by using an unfamiliar organizational pattern.

UsIng COnvenTIOnal PaTTerns OF OrganIzaTIOn

This chapter presents a number of conventional, or commonly used, patterns of organization, such as the chronological pattern and the spatial pattern. You should begin by asking yourself whether a conventional pattern for pre- senting your information already exists. Using a conventional pattern makes things easier for you as a writer and for your audience.

For you, a conventional pattern serves as a template or checklist, helping you remember which information to include and where to put it. In a pro- posal, for example, you include a budget, which you put near the end or in an appendix. For your audience, a conventional pattern makes your document easier to read and understand. Readers who are familiar with proposals can find the information they want because you have put it where others have put similar information.

Does this mean that technical communication is merely a process of fill- ing in the blanks? No. You need to assess the writing situation continuously as you work. If you think you can communicate your ideas better by modify- ing a conventional pattern or by devising a new pattern, do so. However, you gain nothing if an existing pattern would work just as well.

dIsPlayIng yOUr OrganIzaTIOnal PaTTern PrOMInenTly

Make it easy for your readers to understand your organizational pattern. Dis- playing your pattern prominently involves three main steps:

• create a detailed table of contents. If your document has a table of contents, including at least two levels of headings helps readers find the information they seek.

• use headings liberally. Headings break up the text, making your pages more interesting visually. They also communicate the subject of the section and improve readers’ understanding.

• use topic sentences at the beginnings of your paragraphs. The topic sentence announces the main point of a paragraph and helps the reader understand the details that follow.

understanding conventional organizational Patterns

Every argument calls for its own organizational pattern. Table 7.1 explains the relationship between organizational patterns and the kinds of informa- tion you want to present.

Long, complex arguments often require several organizational patterns. For instance, one part of a document might be a causal analysis of the prob- lem you are writing about, and another might be a comparison and contrast of two options for solving that problem. Figure 7.1, an excerpt from a user’s manual, shows how different patterns might be used in a single document.

ChrOnOlOgICal

The chronological—or timeline—pattern is commonly used to describe events. In an accident report, you describe the events in the order in which they occurred. In the background section of a report, you describe the events that led to the present situation. In a set of slides for an oral presentation, you explain the role of social media in U.S. presidential elections by discussing each of the presidential elections, in order, since 2000.

Organizing Information Chronologically

these three suggestions can help you write an effective chronological passage.

Provide signposts. if the passage is more than a few hundred words long, use headings. Choose words such as step, phase, stage, and part, and consider num- bering them. Add descriptive phrases to focus readers’ attention on the topic of the section:

rganIzIng yOUr InFOrMaTIOn

Phase One: determining Our Objectives step 3: installing the lateral supports

At the paragraph and sentence levels, transitional words such as then, next, first, and finally will help your reader follow your discussion.

consider using graphics to complement the text. Flowcharts, in particular, help you emphasize chronological passages for all kinds of readers, from the most expert to the general reader.

Analyze events where appropriate. When you use chronology, you are explain- ing what happened in what sequence, but you are not necessarily explaining why or how an event occurred or what it means. For instance, the largest section of an accident report is usually devoted to the chronological discussion, but the report is of little value unless it explains what caused the accident, who bears responsibility, and how such accidents can be prevented.

sPaTIal

The spatial pattern is commonly used to describe objects and physical sites. In an accident report, you describe the physical scene of the accident. In a feasibility study about building a facility, you describe the property on which it would be built. In a proposal to design a new microchip, you describe the layout of the new chip.

these three suggestions can help you write an effective spatial passage.

Provide signposts. help your readers follow the argument by using words and phrases that indicate location (to the left, above, in the center) in headings, topic sentences, and support sentences.

consider using graphics to complement the text. diagrams, drawings, photo- graphs, and maps clarify spatial relationships.

Analyze events where appropriate. A spatial arrangement doesn’t explain itself; you have to do the analysis. A diagram of a floor plan cannot explain why the floor plan is effective or ineffective.

general TO sPeCIFIC

The general-to-specific pattern is useful when your readers need a gen- eral understanding of a subject to help them understand and remember the details. For example, in a report, you include an executive summary—an overview for managers—before the body of the report. In a set of instructions, you provide general information about the necessary tools and materials and about safety measures before presenting the step-by-step instructions. In a blog, you describe the topic of the blog before presenting the individual blog posts.

Figure 7.4, from the U.S. Department of State, explains the principles underlying the nation’s cybersecurity policy.

MOre IMPOrTanT TO less IMPOrTanT

The more-important-to-less-important organizational pattern recognizes that readers often want the bottom line—the most-important information— first. For example, in an accident report, you describe the three most important factors that led to the accident before describing the less-important factors. In a feasibility study about building a facility, you present the major reasons that the proposed site is appropriate, then the minor reasons. In a proposal to design a new microchip, you describe the major applications for the new chip, then the minor applications.

For most documents, this pattern works well because readers want to get to the bottom line as soon as possible. For some documents, however, other patterns work better. People who write for readers outside their own com- pany often reverse the more-important-to-less-important pattern because they want to make sure their audience reads the whole discussion. This reversed pattern is also popular with writers who are delivering bad news. For instance, if you want to justify recommending that your organization not go ahead with a popular plan, the reverse sequence lets you explain theproblems with the popular plan before you present the plan you recommend. Otherwise, readers might start to formulate objections before you have had a chance to explain your position.

Organizing Information from

General to Specific

these two suggestions can help you use the general-to-specific pattern effectively.

Provide signposts. explain that you will address general issues first and then move on to specific concerns. if appropriate, incorporate the words general and specific or other relevant terms in the major headings or at the start of the text for each item you describe.

consider using graphics to complement the text. diagrams, drawings, photo- graphs, and maps help your reader understand both the general information and the fine points.

Organizing Information from More

Important to Less Important

these three suggestions can help you write a passage organized from more impor- tant to less important.

Provide signposts. tell your readers how you are organizing the passage. For instance, in the introduction of a proposal to design a new microchip, you might write, “the three applications for the new chip, each of which is discussed below, are arranged from most important to least important.”

in creating signposts, be straightforward. if you have two very-important points and three less-important points, present them that way: group the two important points and label them something like “Major Reasons to Retain Our Current Management structure.”then present the less-important factors as “Other Reasons to Retain Our Current Management structure.” Being straightfor- ward makes the material easier to follow and enhances your credibility.

explain why one point is more important than another. don’t just say that you will be arranging the items from more important to less important. explain why the more-important point is more important.

consider using graphics to complement the text. diagrams and numbered lists often help to suggest levels of importance.

COMParIsOn and COnTrasT

Typically, the comparison-and-contrast pattern is used to describe and evalu- ate two or more items or options. For example, in a memo, you compare and contrast the credentials of three finalists for a job. In a proposal to design a new microchip, you compare and contrast two different strategies for design- ing the chip. In a video explaining different types of low-emissions vehicles, you compare and contrast electric cars and hybrids.

The first step in comparing and contrasting two or more items is to deter- mine the criteria: the standards or needs you will use in studying the items. For example, if a professional musician who plays the piano in restaurants was looking to buy a new portable keyboard, she might compare and contrast available instruments using the number of keys as one criterion. For this person, 88 keys would be better than 64. Another criterion might be weight: lighter is better than heavier.

Almost always, you will need to consider several or even many criteria. Start by deciding whether each criterion represents a necessary quality or merely a desirable one. In studying keyboards, for instance, the number of keys might be a necessary quality. If you need an 88-key instrument to play your music, you won’t consider any instruments without 88 keys. The same thing might be true of touch-sensitive keys. But a MIDI interface might be less important, a merely desirable quality; you would like MIDI capability, butyou would not eliminate an instrument from consideration just because it doesn’t have MIDI.

Two typical patterns for organizing a comparison-and-contrast discussion are whole-by-whole and part-by-part. The following example illustrates the difference between them. The example shows how two printers—Model 5L and Model 6L—might be compared and contrasted according to three criteria: price, resolution, and print speed.

Organizing Information by

Comparison and Contrast

these four suggestions can help you compare and contrast items effectively.

establish criteria for the comparison and contrast. Choose criteria that are con- sistent with the needs of your audience.

evaluate each item according to the criteria you have established. draw your conclusions.

organize the discussion. Choose either the whole-by-whole or the part-by-part pattern or some combination of the two. then order the second-level items.

consider using graphics to complement the text. Graphics can clarify and em- phasize comparison-and-contrast passages. diagrams, drawings, and tables are common ways to provide such clarification and emphasis.

You can have it both ways. You can begin with a general description of the various items and then use a part-by-part pattern to emphasize particular aspects.

Once you have chosen the overall pattern—whole-by-whole or part-by- part—you decide how to order the second-level items. That is, in a whole- by-whole passage, you have to sequence the aspects of the items or options being compared; in a part-by-part passage, you have to sequence the items or options themselves.

Figure 7.6 shows a comparison-and-contrast table about employment in the labor force.

ETHICS NOTE

COMParIng and COnTrasTIng FaIrly

Because the comparison-and-contrast organizational pattern is used frequently in evaluating items, it appears often in product descriptions as part of the argument that one company’s products are better than a competitor’s. there is nothing unethical in this. But it is unethical to misrepresent items, such as when writers portray their own product as better than it is or portray their competitor’s as worse than it is.

Obviously, lying about a product is unethical. But some practices are not so easy to character- ize. For example, suppose your company makes tablet computers and your chief competitor’s model has a longer battery life than yours. in comparing and contrasting the two tablets, are you ethically obligated to mention battery life? no, you are not. if readers are interested in battery life, it is their responsibility to figure out what your failure to mention battery life means and seek further information from other sources. if you do mention battery life, however, you must do so honestly, using industry-standard techniques for measuring it. you cannot measure your tablet’s battery life under one set of conditions and your competitor’s under another set.

ClassIFICaTIOn Or ParTITIOn

Classification is the process of assigning items to categories. For instance, all the students at a university could be classified by sex, age, major, and manyother characteristics. You can also create subcategories within categories, such as males and females majoring in business.

Classification is common in technical communication. In a feasibility study about building a facility, you classify sites into two categories: domes- tic or foreign. In a journal article about ways to treat a medical condition, you classify the treatments as surgical or nonsurgical. In a description of a major in a college catalog, you classify courses as required or elective.

Partition is the process of breaking a unit into its components. For example, a home-theater system could be partitioned into the following components: TV, amplifier, peripheral devices such as DVD players, and speakers. Each component is separate, but together they form a whole system. Each compo- nent can, of course, be partitioned further.

Partition is used in descriptions of objects, mechanisms, and processes. In an equipment catalog, you use partition to describe the major componentsof one of your products. In a proposal, you use partition to present a detailed description of an instrument you propose to develop. In a brochure, you explain how to operate a product by describing each of its features.

In Figure 7.7, the writer uses classification effectively in introducing cat- egories of tornados to a general audience.

Figure 7.8 illustrates partition. For more examples of partition, see Chapter 20, which includes descriptions of objects, mechanisms, and processes.

Organizing Information by

Classification or Partition

these six suggestions can help you write an effective classification or partition passage.

choose a basis of classification or partition that fits your audience and pur- pose. if you are writing a warning about snakes for hikers in a particular state park, your basis of classification will probably be whether the snakes are poison- ous. you will describe all the poisonous snakes, then all the nonpoisonous ones.

use only one basis of classification or partition at a time. if you are classifying graphics programs according to their technology—paint programs and draw programs—do not include another basis of classification, such as cost.

Avoid overlap. in classifying, make sure that no single item could logically be placed in more than one category. in partitioning, make sure that no listed com- ponent includes another listed component. Overlapping generally occurs when you change the basis of classification or the level at which you are partitioning a unit. in the following classification of bicycles, for instance, the writer introduces a new basis of classification that results in overlapping categories:

—mountain bikes —racing bikes —comfort bikes —ten-speed bikes

the first three items share a basis of classification: the general category of bicycle. the fourth item has a different basis of classification: number of speeds. Adding the fourth item is illogical because a particular ten-speed bike could be a moun- tain bike, a racing bike, or a comfort bike.

be inclusive. include all the categories necessary to complete your basis of clas- sification. For example, a partition of an automobile by major systems would be incomplete if it included the electrical, fuel, and drive systems but not the cooling system. if you decide to omit a category, explain why.

Arrange the categories in a logical sequence. use a reasonable plan, such as chronology (first to last), spatial development (top to bottom), or importance (most important to least important).

consider using graphics to complement the text. Organization charts are com- monly used in classification passages; drawings and diagrams are often used in partition passages.

PrOBleM-MeThOds-sOlUTIOn

The problem-methods-solution pattern reflects the logic used in carrying out a project. The three components of this pattern are simple to identify:

• Problem. A description of what was not working (or not working effectively) or what opportunity exists for improving current processes.

• methods. The procedures performed to confirm the analysis of the problem, solve the problem, or exploit the opportunity.

• solution. The statement of whether the analysis of the problem was correct or of what was discovered or devised to solve the problem or capitalize on the opportunity.

The problem-methods-solution pattern is common in technical communi- cation. In a proposal, you describe a problem in your business, how you plan to carry out your research, and how your deliverable (an item or a report) can help solve the problem. In a completion report about a project to improve a manufacturing process, you describe the problem that motivated the project, the methods you used to carry out the project, and the findings: the results, conclusions, and recommendations.

Organizing Information by

Problem-Methods-Solution

these five suggestions can help you write an effective problem-methods-solution passage.

in describing the problem, be clear and specific. don’t write, “Our energy expen- ditures are getting out of hand.” instead, write, “Our energy usage has increased 7 percent in the last year, while utility rates have risen 11 percent.”then calculate the total increase in energy costs.

in describing your methods, help your readers understand what you did and why you did it that way. you might need to justify your choices. Why, for example, did you use a t-test in calculating the statistics in an experiment? if you can’t defend your choice, you lose credibility.

in describing the solution, don’t overstate. Avoid overly optimistic claims, such as “this project will increase our market share from 7 percent to 10 percent within 12 months.” instead, be cautious: “this project could increase our market share from 7 percent to 10 percent.”this way, you won’t be embarrassed if things don’t turn out as well as you had hoped.

choose a logical sequence. the most common sequence is to start with the prob- lem and conclude with the solution. however, different sequences work equally well as long as you provide a preliminary summary to give readers an overview and in- clude headings or some other design elements to help readers find the information they want (see Chapter 11). For instance, you might want to put the methods last if you think your readers already know them or are more interested in the solution.

consider using graphics to complement the text. Graphics, such as flowcharts, diagrams, and drawings, can clarify problem-methods-solution passages.

Figure 7.9 shows the problem-methods-solution pattern. The passage is from a case study of a police department using TASER equipment to solve two problems.

CaUse and eFFeCT

Technical communication often involves cause-and-effect discussions. Sometimes you will reason forward, from cause to effect: if we raise the price of a particular product we manufacture (cause), what will happen to our sales (effect)? Sometimes you will reason backward, from effect to cause: productivity went down by 6 percent in the last quarter (effect); what factors led to this decrease (causes)? Cause-and-effect reasoning, therefore, provides a way to answer the following two questions:

• What will be the effect(s) of X? • What caused X?

Arguments organized by cause and effect appear in various types of technical communication. In an environmental impact statement, you argue that a proposed construction project would have three important effects on the ecosystem. In the recommendation section of a report, you argue that a recommended solution would improve operations in two major ways. In a memo, you describe a new policy and then explain the effects you anticipate the policy will have.

Cause-and-effect relationships are difficult to describe because there is no scientific way to determine causes or effects. You draw on your common sense and your knowledge of your subject. When you try to determine, for example, why the product your company introduced last year sold poorly, you start with the obvious possibilities: the market was saturated, the product was of low quality, the product was poorly marketed, and so forth. The more you know about your subject, the more precise and insightful your analysis will be.

But a causal discussion can never be certain. You cannot prove why a product failed in the marketplace; you can only explain why the factors you are identifying are the most plausible causes or effects. For instance, to make a plausible case that the main reason for the product’s weak performance is that it was poorly marketed, you can show that, in the past, your company’s other unsuccessful products were marketed in similar ways and your com- pany’s successful products were marketed in other ways.

Figure 7.10 illustrates an effective cause-and-effect argument. The writer is explaining why electric vehicles have not sold well in the United States.

Organizing Information by Cause and Effect

these four suggestions can help you write an effective cause-and-effect passage.

explain your reasoning. to support your claim that the product was marketed poorly, use specific facts and figures: the low marketing budget, delays in begin- ning the marketing campaign, and so forth.

Avoid overstating your argument. For instance, if you write that Bill Gates, the co-founder of Microsoft, “created the computer revolution,” you are claiming too much. it is better to write that Gates “was one of the central players in creating the computer revolution.”

Avoid logical fallacies. logical fallacies, such as hasty generalizations or post hoc reasoning, can also undermine your discussion.

consider using graphics to complement the text. Graphics, such as flowcharts, organization charts, diagrams, and drawings, can clarify and emphasize cause- and-effect passages.

WRITER’S CHECkLIST

Did you analyze your audience and purpose?

(p. 147)

Did you consider using a conventional pattern of organization? (p. 148)

Did you display your organizational pattern prominently by creating a detailed table of contents? (p. 149)

using headings liberally? (p. 149) using topic sentences at the beginnings of your

paragraphs? (p. 149) The following checklists cover the eight organizational

patterns discussed in this chapter.

Chronological and spatial

Did you provide signposts, such as headings and transitional

words or phrases? (pp. 151, 153) consider using graphics to complement the text?

(pp. 152, 153) analyze events where appropriate? (pp. 152, 153)

general to specific

Did you provide signposts, such as headings and transitional

words or phrases? (p. 154) consider using graphics to complement the text?

(p. 154)

More Important to less Important

Did you provide signposts, explaining clearly that you are using

this organizational pattern? (p. 156)

explain why the first point is the most important, the second is the second most important, and so forth? (p. 156)

consider using graphics to complement the text?

(p. 156)

Comparison and Contrast

Did you establish criteria for the comparison and contrast?

(p. 158)

evaluate each item according to the criteria you established? (p. 158)

organize the discussion by choosing the pattern— whole-by-whole or part-by-part—that is most appropriate for your audience and purpose? (p. 158)

consider using graphics to complement the text? (p. 158)

Classification or Partition

Did you choose a basis of classification or partition that fits your

audience and purpose? (p. 160) use only one basis of classification or partition at a time?

(p. 160) avoid overlap? (p. 160) include all the appropriate categories? (p. 160) arrange the categories in a logical sequence? (p. 160) consider using graphics to complement the text? (p. 160)

Problem-Methods-solution

Did you describe the problem clearly and specifically? (p. 162) if appropriate, justify your methods? (p. 163) avoid overstating your solution? (p. 163) arrange the discussion in a logical sequence? (p. 163) consider using graphics to complement the text? (p. 163)

Cause and effect

Did you explain your reasoning? (p. 165) avoid overstating your argument? (p. 165) avoid logical fallacies? (p. 165) consider using graphics to complement the text? (p. 165)