Jerz > Writing > Technical > Short Reports [ 1 | 2 | 3 ]
Summary: Short blocks of text, divided up into sections with standard labels, convey technical information more efficiently than the cleverly-crafted paragraphs your literature teachers praised. This document describes six sections commonly found in technical reports.
10 Nov 2001; Dennis G. Jerz
The section heading is probably the most important organizational tool for a technical writer. Busy professionals can easily skip over the parts they don’t want to read, and find the parts they do. (Bulleted lists and bold keywords will also help.)
If your document is only a few pages long, you might think of combining closely related sections, such as the introduction and background. On the other hand, you may wish to split the discussion section up into subsections, such as “Problems”, “Methods” and “Solution.” Or, you might add a separate section for recommendations, or add optional end-matter such as a glossary or an appendix that contains all your raw data.
The title block is the first thing your reader sees, and will affect how useful your whole document appears to be. Identify the author, date, and sponsoring organization. Students should specify the course and section number. Include the instructor’s name too (just in case you accidentally slip it under the wrong door).
If your document is only a few pages long, don’t waste a whole page on the title block — that will look like padding. Instead, try including the abstract on the first page. If you are writing an e-mail, your title block (date, sender, recipient) will mostly be handled by your e-mail application. You should, in any case, write a meaningful subject line. People who get a lot of e-mail will tend to ignore messages that aren’t clearly relevant to them. (See: “E-Mail: Top 10 Tips for Writing It Effectively“)
A generic label (such as “Progress Report”) is a wasted opportunity to inform. A useful title not only identifies the subject, but, if at all possible, also delivers the main point of the report.
| Usability Testing Report | |
| Technical Writing Assignment | |
| Students tend to write uninformative titles for classroom assignments, and they can generally get away with it, since it’s the instructor’s job to read every assignment, no matter how uninteresting. But students shouldn’t plan on all professional readers to be quite so devoted to reading. | |
| Usability Testing of 5 Users Accomplishing 10 Tasks on the UWEC English Department Website | |
| Short Reports: How to Write Stunning Technical Documents that Will Make People Love You and Add Years to Your Life | |
| Avoid meaningless, distracting details, or language that overstates your case. A technical writer is not a cheerleader. | |
| Usability Testing of UWEC English Department Website: Imperfect but Good Enough | |
| Short Reports: How to Write Routine Technical Documents | |
| Good titles should not merely identify the form of the document, but the subject as well. If you can communicate your conclusion as well, then your reader will begin reading your document with a much clearer idea of what he or she stands to gain from it. | |
| Digital camcorders. | |
| Such a title is far too vague. What will I learn about digital camcorders if I read this report? | |
| Which Camcorder is Most Reliable? | |
| This title asks a question, but doesn’t answer it. This is a marketing/advertising trick. The goal is to tease, and thus make you sit through advertisements, rather than to inform and thus send you on your way. | |
| Depending on your client’s goals and the needs of your audience, the methodology and scope of the report may be more important than the answer to the question. In a different situation, your primary audience may instead appreciate a title that answers the question right away. | |
| Technical benchmark testing of 12 digital camcorders. The VidMaster 3000 is the cheapest to own and upgrade, but the SuperCorder XT has more complex features. | |
| A comparative field study of the performance, repair record, and durability of digital camcorders. | |
| The VidMaster 3000 and the SuperCorder XT The Most Reliable Mid-Price Camcorders in 2001 A comparative field study of the performance, repair record, and durability of 12 digital camcorders. | |
| Which Camcorder is Most Reliable? The VidMaster 3000 is inexpensive and durable, but the SuperCorder XT gives the best performance. | |
| Consider the effect of the title on the reader. How do the various “good” titles (listed above) change your expectations of the rest of the report? | |
The abstract or summary is a miniature version of the entire report, written for the convenience of a reader who can’t or won’t plough through the whole thing.
Begin a 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. Imagine your reader will see nothing but the abstract — because in many cases that will be true.
(See: “Begin with Your Conclusion: The Inverted Pyramid in Technical Writing“).
Because the abstract will be the first thing your reader sees, you should write it last — after you have figured out exactly what you want to say.
No puffery or babbling. Make the most efficient use of 100-200 words (or a little more for documents longer than 50 pages).
Your busy readers will appreciate informative subheadings, bulleted lists and bold keywords — all of which save them from having to plough through boring paragraphs looking for the information they want.
A technical document is not a mystery novel. Don’t build to a conclusion, and don’t expect the reader to wait until the end to learn your findings (that is, your statistics and results). Present the most important stuff immediately; be specific. Save the full explanation for the body of your report.
Give your readers what they want as quickly as possible. Too many abstracts waste words promising and teasing, when they could more usefully deliver the Cliffs Notes version of the contents — a concise, factual summary, that uses far fewer words.
How would you feel if you came across the following article in the sports section?
This article will describe the outcome of a recent sporting event. It will identify the opposing teams, present the final score, describe a few key plays, and present a few short quotes from selected athletes and their coaches. The article will also evaluate the performance statistics of certain players, and speculate about how the specific outcome of this game may affect upcoming games.
The above paragraph is a waste of time! What is it missing?
The abstract is not merely a string of promises , but actually delivers the content in a condensed form.
| This document analyzes the chemical equation described on page 2. It begins with a general introduction, provides a brief background, discusses the problem, and recommends a solution. | |
| Don’t expect the reader to consult internal pages or figures to figure out what you mean. The above abstract is a table of contents, rather than a condensed version of the contents. | |
| This document will compare three candidates for promotion to area manager, and recommend the best one. | |
| The above sentence simply lays out a plan for the document; it doesn’t actually deliver any of the content that the document contains. (For instance, who’s getting the recommendation?) | |
| The Internal Review Committee recommends Gus Goodwright for promotion to area manager, based on previous experience, monthly productivity reports, and a personal interview. | |
| The revision (above) not only names the “best” candidate, but it offers three criteria.If the full document is short (a page or so), the single sentence above is probably sufficient for both the abstract and the introduction. If the report is longer than that, you should add more detail. | |
| The Internal Review Committee recommends Gus Goodwright for promotion to area manager, based on previous experience, monthly productivity reports, and a personal interview. While candidates Sally Slacker and Poindexter J. Cashgrubber have more years of experience than Goodwright, and while Cashgrubber regularly equals or betters Goodwright’s monthly sales figures, the committee unanimously agreed that Goodwright’s exceptional performance during the on-site interview makes him the best choice. Should Goodwright turn down the offer, most committee members agreed that Poindexter would make an acceptable second choice, but a minority was in favor of seeking additional candidates instead. | |
| The above abstract doesn’t try to justify every claim that it makes; it merely reports the results. Interested readers can consult the full report for more details. | |
Like the abstract, the executive summary is a compressed version of the full report. The abstract is generally written for an insider — the engineers, health care workers, or consumers who will actually use the document. The executive summary is written for an interested outsider — a more distant figure who wants to know how your report will affect other parties.
For example, you probably know more about your own particular project and subject than the superiors a few steps up your institutional hierarchy. The higher-ups are probably not interested in debating your conclusions or checking your equations. (Your immediate supervisor will probably do that.)
| Case Study: Who Reads an Executive Summary?A company’s chemical engineering group may produce a report recommending that a company should purchase a particular kind of rubber from a vendor, rather than continue the less-expensive policy of manufacturing an inferior alternative on site. That report will have an abstract, written for the benefit of fellow engineers, suppliers and industrial customers — all of whom may find the chemical formulae and data charts a compelling argument for making the switch. But the company officials who were hired because of their financial or managerial skills won’t be interested in the chemical make-up of the substances being compared. These executives will be more interested in figuring out how many workers will be retrained or fired, whether the existing production facility should be refurbished or sold, and who knows what else. The report probably won’t be expected to have all the answers the executives need; but after reading a good executive summary, these interested outsiders will be able to connect the dots on their own. What if the union covering the affected workers has negotiated an agreement protecting them from sudden mass firings? Each affected employee might be entitled to so much severance pay that the switch will end up costing the company too much money in the short run.The big-picture situation involves more variables than the chemical engineers — specialists, who do not have access to all the information sources in the walnut-paneled offices — are expected to account for. |
Rank-and-file workers won’t be expected to produce an executive summary that answers all the questions an executive might have; but the first rule of technical writing is “know your audience.” Find out which higher-ups are likely to read your document, and — if you really want to make a good impression on them — craft a summary that will meet their special needs.
This section should introduce the specific document, not the whole subject. Think of your introduction as an annotated table of contents, rather than an opportunity for you to prove how much you know about the subject.
While the abstract is a miniature version of the content of your report, the introduction is a concise preview of the document’s structure. The purpose of the introduction is toacquaint the reader with the structure of your report, not to provide a general overview of the subject matter. (Your abstract will do that.)
You probably feel that you had to cut a lot of details and simplify the issues when you composed your abstract. If so, the introduction can point the reader to these areas of greater complexity. For a short document with a simple structure, your introduction may be nothing more than a purpose statement.
Use the introduction to answer the following questions:
| If you have nothing unusual to say in your introduction, avoid padding: | |
| The purpose of this document is to communicate the results of a lab report. The background section provides general information. The equipment section describes the lab setup, and the methods section presents the procedures followed during the lab. The findings are detailed in the results section, and the conclusion section provides final recommendations. | |
| …and water is wet, and the pope is Catholic.The above example could have been written for almost any lab report, no matter its subject matter, point of view, credibility or relevance. But it conveys no useful information about this particular lab report, and is therefore a waste of words. | |
| This web site describes how to write a short technical report. The primary audience is beginning technical writing students, but it should also help anyone unsure of how to present complex information in a professional setting. Each component of a short technical report is defined and explained via examples, commentary, and selected links to additional resources. | |
The background section introduces the reader to the subject matter of the report. This section should place this particular report in context. Write it mostly for newbies — a recent hire, a student who will take the same course next year, or yourself years from now, after you have forgotten most of the details bouncing around in your head right now.
The background section should focus first on information that will benefit all readers, and then move on to information that benefits smaller groups.
As soon as readers encounter a fact that they already know, they will probably skip ahead to the next section. If your background presents different kinds of background information (history of the project, list of personnel and materials used in this phase, and an overview of recent scholarly publications on the subject) you should list the kinds of background that your report will provide, and clearly label each subsection, so that readers can jump directly to the parts they need to read.
Address questions like the following:
The discussion section is the meat of your report. This is where you give all the details that you’ve been preparing your reader for all along. Describe your expectations; present your data; and explain why test user #4’s scores were abnormally high.
Don’t simply dump a truckload of data in your reader’s lap. You still need to use the inverted pyramid, beginning this section and each subsection with a miniature, local abstract (or at least a local introduction). Begin with information that is already familiar to your reader, and work carefully towards unfamiliar material.
If you haven’t been given a specific outline to follow, divide this section up however you wish. You don’t even have to label this part of the report “discussion.” Just make sure that each subsection begins with a miniature abstract and introduction of its own, previewing the content and structure that will follow.
Divide the discussion section into smaller subsections, following an organizational principle such as these:
Your reader has already probably read the abstract, and thus has some idea of what the completed picture is supposed to look like. Here is where you line the pieces up, so that you can demonstrate (in the final sections of your report) how carefully and neatly they snap together.
By the time your readers get to the conclusion section, they should already have read your main point several times — in the first few lines of the introduction, in the abstract, and even in the title of the paper. Most technical documents should not build to a conclusion, so nothing that you say at the end of your document should be a surprise.
If your report investigated a question, what’s the answer? What have you (and your readers) learned? Present your global findings first (“Test subjects were briefly confused by the navigation bar, but managed to complete the tasks quickly.”) before you dutifully list the full results of each separate measurement (“For question one, 40% answered ‘yes’. For question two…”).
| Therefore, this report has shown that [repeat purpose here]. | |
| Some technical documents don’t need a large conclusion section. If you have stated your main point in your abstract and in the purpose statement of your introduction, and you can’t think of much else to say, don’t pad this section.On the other hand, you might wish to present your experimental results, make a recommendation, or otherwise provide a detailed explanation of your final outcome. If so, you may split the conclusion section up into “results”, “recommendation”, or “action items,” but don’t create so many padded subdivisions that you end up diluting your findings. | |
If you include a results section, it should compile, filter, and organize — with your strongest findings first — all the evidence that supports the claims that you want to make.
Your reader is only interested in your data insofar as it supports whatever claims your paper is making. Instead of making your reader slog through all the raw data, you should instead focus on the issues that emerged. (Of course, your report should describe false starts or dead ends — but only after the more important, more useful, information has been presented.)
For example, you might begin by stating that your test results determined that option A will be 35% faster, and 24% more accurate, but 15% more expensive, than option B. Briefly list the kinds of data that led to the “faster” result, the “more accurate” result, and the “more expensive” result. Now that you’ve given a brief overview of all your findings, you’re ready to start trotting out your analyses of the specific measurements that led to your conclusions.
Also present contradicting or anomalous evidence, in sufficient detail that permits you to argue that your claims are still valid. If you admit the gaps and weaknesses in your argument (many of which will be spotted anyway by critical readers), your stronger points will likely be more convincing. For a very short document, the results, recommendations, and conclusions may be so closely entwined that it would make little sense to isolate them in different sections. Instead, you could slip the findings into the end of the discussion section, and combine the recommendations and conclusions into a single section (with whatever name you feel is most appropriate).. A lengthier report may yield several discrete kinds of findings.
This is the place where you discuss at length all the details you had to drop when you touched on the significance of your findings elsewhere. Go ahead and repeat your main point, but do so efficiently, without appearing to beat a dead horse. Use it as a launch pad for an analysis of additional conclusions, hypotheses, or unanswered questions — but don’t bring in new and completely unrelated topics for the first time.
Your reader may not have read all the sections of your report as thoroughly as an ideal reader would have. A little repetition won’t hurt — but don’t cut and paste whole sentences from previous sections.
A report that recommends ditching a particular product line and selling a factory may draw on user testing results, marketing research, federal court cases, and local zoning laws. While the reader should already have read (in the abstract, introduction, and discussion) about all the major factors that led to your decision, you may not have explained, in detail, how those separate pieces fit together. Describe those factors here — individually, but as part of a carefully crafted structure — to make your conclusion flow more smoothly.
Dennis G. Jerz
25 Oct 2001 — rough draft first posted
10 Nov 2001 — last modified
11 Oct 2007 — typo corrected
23 Aug 2012 — reformatted, links updated
Technical Writing > Short Reports [ 1 | 2 | 3 ]
View Comments