Macro-Organization of Technical Documents: Part I (For EPD 397 Reports and Team-Written Senior...

transcript

Macro-Organization of Technical Documents: Part I

(For EPD 397 Reports and Team-Written Senior Design Reports)

Our purpose is to supplement, not replace the advice and instructions offered by your professors or your supervisor.

Students who complete Part 1 of this module should be able to

1. Make better decisions about when to use a generic report structure, and avoid the pitfalls of those structures.

2. “Tell us a story” about the technical research: design a structure around a clear purpose, avoiding irrelevant and unrelated information.

3. Draft a working outline that captures key points and establishes a logical progression for the technical story.

4. Transform a working outline into useful, specific headings and subheadings that convey the purpose of the document.

5. Further enhance the logic, hierarchy of ideas and balance by evaluating relationships between headings and subheadings.

6. Condense the outline into a useful, specific Table of Contents, enabling readers to quickly skim for key content areas and efficiently determine the key purpose of the document.

Learning Objectives: Part 1

Before even thinking about macro-organization, gather research and generate ideas: keep your focus on audience needs.

Audience needs

Once your preliminary information gathering stage is done, you can begin to draft a working outline.

Technical Reports in science and engineering typically follow a generic structure that can be useful for grouping research.

I. Introduction

II. Related Work

III. Implementation (what we did)

IV. Evaluation (how we tested the validity of our solution)

V. Conclusions and Future Work

A similarly generic structure for technical reports is known as the “IMRD” structure.

I. Introduction (a literature review with emphasis on an existing “research gap”)

II. Methods (may include both theory and approach)

III. Results of primary research (data generated)

IV. Discussion of results (analysis and interpretation of the data)

V. Conclusions

What problems do IMRD and other generic report structures present for organizing ideas?

Can this generic structure, “IMRD,” be usefully adapted?

I. Introduction (a literature review with emphasis on an existing “research gap”)

II. Methods (may include both theory and approach)

III. Results of primary research (data generated)

IV. Discussion of results (analysis and interpretation of the data)

V. Conclusions

When reporting results of research, strive to tell us a story – with a beginning, a middle, and an end:

Where do we go from here?

When performing a technical analysis using secondary research, strive to tell us a story, too – with a beginning, a middle, and an end:

Where do we go from here?

One strategy for beginning to capture and visualize your “technical story” is to use sticky notes for key parts of the story.

Examine the haphazardly arranged “sticky notes” below, and think about a logical order for these ideas.

You may have arranged your sticky notes in the order represented below:

Breaking those sentence-length ideas into sub-points can help us better understand and emphasize logical relationships between ideas.

Don’t simply generate an outline and then forget it; continue to develop, reconsider, and sharpen your outline as you write.

How do we create headings and subheadings that effectively demonstrate a strong macro-organization?

An outline that is not specific enough will not help us understand the writer’s purpose.

• Introduction• Background• Body: Controversies• Analysis• Conclusion

Specificity?

Story?

This outline is still too general: the headings are so broad that the logic and the story are unclear.

Test your outline: if the order of sections doesn’t make any difference, you don’t have a story; you have an information dump.

Here is the same outline with improved specificity, but the hierarchy of ideas is still not clear.

I. Introduction: Existing Radioactive Waste Storage CrisisII. Characteristics of High-Level Radioactive WasteIII. Yucca Mountain Site GeologyIV. Area Demographics V. Budgetary ConcernsVI. Local ResistanceVII. Environmental ConcernsVIII. Transportation Concerns (from Onsite Storage to Site)IX. Conclusions and Recommendations

Consider this improved hierarchy of ideas – with embedded subheadings; here structure emphasizes purpose.

1. Introduction: Existing Radioactive Waste Storage Crisis2. Characteristics of High-Level Radioactive Waste3. Arguments Supporting Yucca Mountain Site

a. Site Geologyb. Area Demographics

4. Arguments Against the Yucca Mountain Sitea. Local Resistance b. Environmental Concernsc. Transportation Concerns (from Onsite Storage to Site)

• Conclusions and Recommendations

Breaking down key points into specific headings and subheadings can help us see where a document might be unbalanced.

How balanced is this outline?

1. Introduction: existing radioactive waste storage crisis2. Characteristics of high-level radioactive waste3. Arguments supporting Yucca Mountain site

a. Site geologyb. Area demographics

4. Arguments against the Yucca Mountain sitea. Local resistance b. Some seismic concernsc. Related environmental concernsd. Transportation concerns (from onsite storage to site)e. Budgetary concerns

5. Conclusions and recommendations24

Some of the same rules for outlines apply to Tables of Content: readers look for logic, specificity, hierarchy, and balance.

“Evaluation of Carbon Fiber Reinforced Polymers for Use in Bridge Pier Repair”

• Introduction 1• Objectives 2

• Background on Pier Damage and Repair3

• Causes of Corrosion 3• Effects of Corrosion 3• Current Pier Repair Methods 3• Carbon Fiber Reinforced Polymers

3• Application Systems 5

• Evaluation of Carbon Fiber Reinforced Polymers6

• Strength and Corrosion Effectiveness8

• Cost and Time Savings 10• Recommendations and Conclusion

12• Glossary 14• References 1526

Revised TOC for “Evaluation of Carbon Fiber Reinforced Polymers for Use in Bridge Pier Repair”

Introduction: Background on Pier Damage 1Causes of Corrosion 1Effects on Steel-Reinforced Piers 2

Conventional Pier Repair Methods 3Pier replacement

3 Traditional reinforcement materials4 Costs and complications of conventional

methods 5Carbon Fiber Reinforced Polymers (CFRP) as a Reinforcement Material 6

Background and properties of CFRP 6Methods of Applying CFRP 7

Evaluation of CFRP vs. Conventional Pier Repair 9Strength and Corrosion Effectiveness 9 Costs and Time Savings 11

Recommendations and Conclusion 13Glossary 14References 15

Consider one more outline draft of a technical report:

Polychlorinated Biphenyl (PCB) Contamination of River Systems:

An Analysis of Remediation Techniques

• Introduction

• Physical, Chemical, and Behavioral Characteristics of PCBs

• Historical Perspective of PCBs in the Pulp and Paper Industry

• Remediation Technologies

– Natural Attenuation

– In-Situ Remediation • Capping• Biological/Chemical Treatment

– Ex-Situ Remediation • Dredging• Dry Excavation

• Situation in the Fox River Valley

• Development of General Relationship

• Conclusion 28

In this so-called analysis, a big chunk of the report appears to be merely informative.

• Introduction

– In-Situ Remediation

• Capping All simply descriptive information?

• Biological/Chemical Treatment

• Conclusion29

Is the analysis buried in a bland section heading?

• Introduction

– In-Situ Remediation • Capping• Biological/Chemical Treatment

• Conclusion 30

Key take-home points from this module:

• Tell us a story about your research.

• Create such a logical progression of ideas that we understand why each section appears where it appears.

• Strive for logic, specificity, hierarchy of ideas, and balance in your headings and subheadings.

• Make the document easy to follow and easy to scan quickly – readers will appreciate that!

ReferencesGoddard, Steven, adapted from work by Douglas Niehaus. “Generic Technical Paper Skeleton.”

Resources for Technical Writing. Univ. of Nebraska, Lincoln. Retrieved from: http://cse.unl.edu/~goddard/WritingResources/Templates/ [Date last modified: May 8, 2009].

Monreal, Carmen Soler; Salom, Luz Gil, and Olivares, Maria. (2006) “A Study of Section Headings in Computing, Robotics, and Telecommunications Research Articles.” RæL 5, 1-26. ISSN: 1885-9089.

Taboada, Maite; Mann, William C. (2006) Rhetorical Structure Theory: looking back and moving ahead. Discourse Studies. 8, 423-459. DOI: 10.1177/1461445606061881

If you have questions or comments on this module, contactLaura Grossenbacher, Ph.D.

grossenb@engr.wisc.eduOffice: M1050B Engineering Centers

Phone: 608-262-8073Technical Communication Program