Begin a short technical report by giving away — as quickly as possible — the information your reader wants.
A technical document is not a mystery novel — it should not hold back in order to build to a stunning conclusion. The body of the document should only repeat and amplify what the reader already knows is coming.
- How informative can you make the first sentence of the first section?
- How informative can you make your title?
As you write, ask yourself the journalist’s questions, “who,” “what,” “when,” “where,” “how,” and “why” — and get the answers to your reader as clearly and efficiently as possible. The document as a whole, and each section within that document, should begin with the most important points, and follow up with lesser ones. Journalists call this style of writing “the inverted pyramid.”
Imagine coming home to find this message on your answering machine:
“I’m being followed, so I can only talk for a minute. In this telephone call, I will reveal the location of a suitcase full of money. I will then explain who gave it to you, and why. This telephone call will then go on to describe how to defuse the boobytrap without attracting unwanted attention from the dozens of armed mercenaries who are out to kill you at this very minute. After you have finished listening to this telephone call, you will be wealthy, healthy, and safe, thanks to the important information that this telephone call has communicated. Uh-oh… I gotta go. [Click!]”
Provide an overview first, giving the most important details as briefly as possible. Then, follow up with more details. In special cases, when you are trying to minimize the impact of very bad news, you might wish to soften up the reader with a little good news before you drop the bomb. (But don’t overdo it.)
Consider the following example of a technical report. Note how the main point is made right away, and repeated with increasing levels of specificity, as the author introduces details.
|College freshmen are frequently surprised, and occasionally shocked, at the differences between A-level high school writing and A-level college writing.||The first sentences states the main point right away.|
|Over a period of three years, a survey of about 150 freshman of composition students at the University of Wisconsin–Eau Claire revealed that students felt that their high school English classes left them largely unprepared for a college writing course.||The next sentence quickly explains the research methodology, since the reader is probably wondering how you know this detail that you’re about to prove.|
|When discussing their difficulty earning the same grades they had received in high school, students regularly invoked the heavier workload, the higher academic standards, and the degree of self-motivation expected of a college student.||This passage very briefly lists supporting points (here set in boldface), repeating and amplifying the paper’s main point.|
|Students typically notice the heavy workload right away, with longer and more complex reading assignments, fewer routine study guides and fill-in-the-blank worksheets, and longer essay assignments. Students soon learn that professors have higher academic standards, being less likely to reward a paper because it has no spelling mistakes, and more likely to challenge logical fallacies, sloppy research, and unsupported personal opinion. Only gradually do students recognize the importance of self-motivation — professors don’t mark every error on returned assignments, or use class time to go over all the assigned readings; revisions (when permitted) often take as long as the original assignment; and professors have little sympathy for students who procrastinate or forget about a deadline.||The three points made in the previous sentence are now repeated, with a full sentence devoted to each. This section once again repeats and amplifies the main point.Note that the sentence that expands upon “heavier workload” offers specific examples (difficulty of reading assignments, the nature of routine coursework, and the length of essay assignments). The reader will probably expect to read even more details on each of those examples, once he or she gets to the full treatment of this point.|
|As a phenomenological study, this paper identifies several specific ways in which these particular college students felt their high school experience was inadequate. While we should be careful when attempting to draw conclusions from students’ opinions of what they believe they have or have not learned, high school and college English teachers may find this study a useful teaching aid, to ease the transition from high school to college.||Offer a short version of the conclusion, with appropriate hedges — ways that the author protects his or her points against valid counter-arguments.(For anybody who came to this page hoping to find a paper about the differences between college and high school writing: This is not an excerpt from a real study — it’s just an example. I haven’t looked at the data closely enough to say anything this definitive. –DGJ)|
Consider the following ways to begin a technical report. Which is easier to comprehend?
|Cold air can enter your house through tiny gaps around windows, doors, exhaust fan outlets, or any other place where hardware or fixtures penetrate the exterior surface of a building. In some residences, hidden openings can let in as much cold air as would come through a hole the size of a brick.|
|The above example launches into the subject without any introduction, which makes it extremely confusing. Is this the introduction to a study of the thermodynamic properties of air? Will the document present the results of scientific testing of several competing brands of caulks and sealants? Is this part of an advertisement for a home maintenance company? The reader can’t tell from the first few sentences what he or she is supposed to learn from the document.|
|This report describes three ways consumers can lower their winter heating bills. Cold air can enter your house through tiny gaps around windows, doors, exhaust fan outlets, or any other place where the exterior surface of your home is penetrated. Caulking and sealing those gaps will make your home more energy efficient.|
|The above revision is somewhat better, because it describes the content — three methods for lowering heating bills. The new introductory sentence specifies who should read the document, and why. Unfortunately, it’s not clear what the three methods are. Is “caulking and sealing” one method, or two? If two, then where’s the third? Maybe the author is trying to say that the three methods are “caulk your windows,” “caulk your doors,” and “caulk your exhaust fans.” If so, then what do we make of “or any other place…”? You should spend a little extra time organizing your document, so that your readers won’t have to make guesses about what you mean to say.|
|Consumers can easily lower their winter heating bills by caulking and sealing, wearing warmer clothes, and letting the sun in whenever possible.|
|Much better! The opening sentence lists the three main points that the document is going to make, adds a clear subheading to help organize the content, and then begins to give the details.|
If you have three or four important facts to present, give them right away in a straightforward list. Follow up with a few sentences contextualizing and explaining each main point, but don’t try to dump all your knowledge at once.
Nobody reads technical information for fun — except maybe Scotty, from the original Star Trek. Since you probably aren’t writing for him, you should help your reader determine whether a particular document is worth reading.
Don’t begin by talking about what your document will do… instead, write a shortened form of the whole document, that attempts to do, in a very small space, whatever it is the whole document is supposed to accomplish. (See the description of an abstract.)
Dennis G. Jerz
25 Oct 2001 — rough draft first posted
10 Nov 2001 — last modified
|Writing Short Technical Reports|
|Think of Your Reader First|
Good writers don’t need fancy words. Who will read your report, and why? Does your document actually deliver what it promises?Use Appropriate Section Headings
For any document longer than a page, break up the content into subsections like introduction, background, discussion, and conclusion.
|Dennis G. Jerz|
Blurbs: How to Write Them for Web Pages
A blurb is a short paragraph that previews what’s on the other end of a link. You’re reading a blurb now. If it helps you decide whether you should click the link, then it has done its job.