Structure-Level Revisions
Paying attention specifically to “big picture” items such as informational value, internal organization, and topic sentences will help ensure that your document clearly conveys your ideas and their relationships to each other. If you revise your document with these things in mind, you’ll be able to more accurately meet your audience’s expectations.
Informational Value
One of the most important ways you can review a rough draft is to check its contents for informational value. No matter how well organized it is or how many good transitions and active sentence structures are included, if your technical document doesn’t contain the appropriate information for its audience, it cannot fulfill its purpose. When reviewing a document for informational value, examine your document for the following issues:
- Information is missing. For example, imagine that somebody wrote a technical report on “virtual communities” but never bothered to define what “virtual community” means. The reader would be utterly lost.
- Information is there but is insufficient. Take the same example and imagine that the writer only made a few vague statements about virtual communities. Readers (unless they are experts on virtual communities) likely need at least a paragraph on the subject, if not a comprehensive three- or four-page section.
- Information is there but at the wrong level for the audience. Imagine that the report’s writer included a two-page explanation of virtual communities but focused on highly technical information and phrased it in language that only a sociologist (an “expert” academic audience) would understand, when the document was really intended for high school students. The writer failed to match the readers’ knowledge, background, and needs.
If you can get a sense of how information does or doesn’t match your audience, you should be well on your way to knowing specifically what you need to do in order to revise.
Internal Organization
If you have the necessary and audience-appropriate information in a technical document, you’re on the right track to crafting a successful document. However, that information may still not be sufficiently organized. When writing and revising a document, consider these two aspects of internal organization—levels (or priority) of information and sequence (or order) of information—on both individual-paragraph and whole-document levels.
Levels of Information
Some paragraphs and sentences contain general information or broader statements about the topic being discussed. Others contain more specific information or go into greater depth. The first type forms a framework that supports the second, subordinate elements of the second type. When thinking about levels of information, envision how a paragraph’s or document’s organization would look in outline format. The broader claims and statements that shape the document would be in Level 1 and Level 2 headings, whereas the detailed evidence, reasoning, and support would appear in lower levels.
When you revise, check if the document’s framework is easy to follow. The most common and effective way to arrange general and specific information is to introduce the framework first, then follow it with specifics. This overarching pattern holds for sentences inside paragraphs and paragraphs inside longer documents, even if the paragraph or document uses a different sequence of information. Reverse outlining, or the practice of creating an outline based off of an already-written document, can also help you visualize the current structure and decide if it needs to change.
Sequence Information
In addition to grouping information according to its levels, organization refers to the order information appears. This order or sequence is crucial to creating documents that make sense and achieve their purpose. As with a document’s content, you will want to match a technical document’s internal sequence of information to the document’s audience, context, and purpose. Here are some examples of common informational sequences (some of these may be familiar to you from the organizational pattern tables in Chapter 3.)
General → specific. Arrange information from general to specific. For example, listing categories of evidence is more general than defining examples of evidence specifically. This pattern is illustrated in Table 8.
| Original Version | Revised Version |
|---|---|
| Making an argument from indirect evidence, also called circumstantial evidence, involves using evidence to make inferences, generally based upon probability, about the causes that led to a set of circumstances. Evidentiary arguments can be made from two categories of evidence, direct and indirect. | Evidentiary arguments can be made from two categories of evidence, direct and indirect. Making an argument from indirect evidence, also called circumstantial evidence, involves using evidence to make inferences, generally based upon probability, about the causes that led to a set of circumstances. |
Simple → complex.
Begin with the simple and fundamental concepts, and then move on to the more complex and technical.
Thing-at-rest → thing-in-motion.
Describe the thing “at rest” (as if in a photograph), then discuss its operation or process (as if in a video).
Spatial movement.
Describe a pattern of physical movement; for example, top to bottom, left to right, or outside to inside.
Temporal movement.
Describe events in relation to what happens first, second, and so on.
Concept → application of the concept/examples.
Discuss a concept in general terms, then discuss the concept’s application and/or examples of the concept.
Data → conclusions.
Present data (observations, experimental data, survey results) then move on to the conclusions that can be drawn from that data. (This pattern is sometimes reversed: present the conclusion first and then the data that supports it.)
Problem/question → solution/answer.
Introduce a problem or raise a question and then move on to the solution or answer.
Simplified version → detailed version.
Discuss a simplified version of the thing, establish a solid understanding of it, then explain it all again, but this time providing the technical details. (This approach is especially useful for explaining technical matters to nonspecialists.)
Most important → least important.
Begin with the most important, eye- catching, dramatic information and move on to information that is progressively less so. (This pattern can be reversed: you can build up to a climax, rather than start with it.)
Strongest → weakest.
Start with the strongest argument for your position to get your audience’s attention, then move on to less and less strong ones. (This pattern can also be reversed: you can build up to your strongest arguments, but the weakest → strongest pattern is often less persuasive.)
The options above are some of many possibilities. Whichever sequence you choose, be consistent and avoid mixing these approaches randomly. For example, presenting some data, stating a few conclusions, and then switching back and forth between data and conclusions will confuse your reader.
