Chapter 2: Applications of Technical Writing
2.2: Types of Technical Documents
By: David McMurrey
Upon completion of this chapter, readers will be able to do the following:
- Identify common types of technical documents.
- Summarize the purposes and formats of common types of technical documents.
Types of Technical Documents
For the final report in some technical-writing courses, you can write one of (or even a combination of) several different types of reports. If there is some other type of report that you know about and want to write, get with your instructor to discuss it.
This chapter briefly defines these different report types; some are covered in full detail elsewhere in this book; the rest are described here. But to get everything in one place, all the reports are briefly defined here, with cross-references to where their presentations occur:
Standard operating policies and procedures: These are the operating documents for organizations; they contain rules and regulations on how the organization and its members are expected to perform. Policies and procedures are like instructions, but they go much further. Standard operating procedures (SOPs) are more for procedures in which a process is performed--for example, taking a dental impression.
Recommendation, feasibility, evaluation reports: This group of similar reports does things like compare several options against a set of requirements and recommend one; considers an idea (plan, project) in terms of its "feasibility," for example, some combination of its technical, economic, social practicality or possibility; passes judgement on the worth or value of a thing by comparing it to a set of requirements, or criteria.
Technical background reports: This type is the hardest one to define but the one that most people write. It focuses on a technical topic, provides background on that topic for a specific set of readers who have specific needs for it. This report does not supply instructions, nor does it supply recommendations in any systematic way, nor does it report new and original data.
Technical guides and handbooks: Closely related to technical report but differing somewhat in purpose and audience are technical guides and handbooks.
Primary research reports: This type presents findings and interpretation from laboratory or field research.
Business plans: This type is a proposal to start a new business.
Technical specifications: This type presents descriptive and operational details on a new or updated product.
Technical Background Reports
The technical background report is hard to define—it's not a lot of things, but it's hard to say what it is. It doesn't provide step-by-step directions on how to do something in the way that instructions do. It does not formally provide recommendations in the way that feasibility reports do. It does not report data from original research and draw conclusions in the way that primary research reports do.
So, what does the technical background report do? It provides information on a technical topic but in such a way that is adapted for a particular audience that has specific needs for that information. Imagine a topic like this: renal disease and therapy. A technical background report on this topic would not dump out a ten-ton textbook containing everything you could possibly say about it. It would select information about the topic suited to a specific group of readers who had specific needs and uses for the information. Imagine the audience was a group of engineers bidding on a contract to do part of the work for a dialysis clinic. Yes, they need to know about renal disease and its therapy, but only to the extent that it has to do with their areas of expertise. Such a background report might also include some basic discussion of renal disease and its treatment, but no more than what the engineers need to do their work and to interact with representatives of the clinic.
One of the reports is an exploration of global warming, or the greenhouse effect, as it is called in the report. Notice that it discusses causes, then explores the effects, then discusses what can be done about it.
Typical contents and organization of technical background reports. Unlike most of the other reports discussed in this course guide, the technical background report does not have a common set of contents. Because it focuses on a specific technical topic for specific audiences who have specific needs or uses for the information, it grabs at whatever type of contents it needs to get the job done. You use a lot of intuition to plan this type of report. For example, with the report on renal disease and treatment, you'd probably want to discuss what renal disease is, what causes it, how it is treated, and what kinds of technologies are involved in the treatment. If you don't fully trust your intuition, use a checklist like the following:
- Definitions—Define the potentially unfamiliar terms associated with the topic. Write extended definitions if there are key terms or if they are particularly difficult to explain.
- Causes—Explain what causes are related to the topic. For example, with the renal disease topic, what causes the disease?
- Effects—Explain what the consequences, results, or effects associated with the topic. With the renal disease topic, what happens to people with the disease; what effects do the various treatments have?
- Types—Discuss the different types or categories associated with the topic. For example, are there different types of renal disease; are there different categories of treatment?
- Historical background—Discuss relevant history related to the topic. Discuss people, events, and past theories related to the topic.
- Processes—Discuss mechanical, natural, human-controlled processes related to the topic. Explain step by step how the process occurs. For example, what are the phases of the renal disease cycle; what typically happens to a person with a specific form of the disease?
- Descriptions—Provide information on the physical details of things related to the topic. Provide information about size, shape, color, weight, and so on. For the engineering-oriented report, this would mean size, power requirements, and other such details about the treatment technologies.
- Comparisons—Compare the topic, or some aspect of it, to something similar or something familiar. With the renal disease example, you could compare renal disease to some other disease; the treatment to some other treatment; the functions of the kidney to something familiar (an analogy); or even the treatment to something familiar, for example, the filter system for a swimming pool.
- Applications—Explore how some aspect of your topic can be used or applied. If it's some new technology, what are its applications?
- Advantages and disadvantages—Discuss the advantages or disadvantages of one or more aspects of your topic. In the renal disease topic, for example, what are the advantages of one treatment over another?
- Economic considerations—Discuss the costs of one or more aspects associated with your topic. How much does treatment for renal disease cost? How much does the equipment and personnel cost?
- Social, political, legal, ethical implications—Explore the implications or impact of your topic or some aspect of it in relation to social, political, legal, or ethical concerns. The renal disease example doesn't lend itself much to this area but imagine the possibilities with a topic like cryogenics—suspended animation of human beings. Often, new technologies have profound impact in these areas.
- Problems, questions—What problems or questions are there associated with your report topic or some aspect of it?
- Solutions, answers—What solutions or answers can you offer on those problems or questions raised by your topic or some aspect of it?
We could add many other categories to a checklist like this, but maybe this is enough to get you started planning the contents of your technical background report. And remember that each of these checklist items may represent a full section in the report—not a sentence or two.
As for the organization of these parts of the report, again, your intuitions are in order. Some subtopics logically come before others.
Typical format of technical background reports. Remember that in most technical-writing courses, you are expected to use a format like this exactly and precisely—unless you work out some other arrangements with your instructor.
Technical Guides and Handbooks
There's a distinction to be made between reports, on the one hand, and guides and handbooks, on the other. However, it's difficult to distinguish between the two latter types. A report, as the preceding section explains, is simply a collection of information on a topic—its background. For example, your boss might call you in and bark out this order: "Jones, our architectural firm needs to catch up with this green roof thing. See if you can pull some basic information together for me. How about in two weeks?"
A guide or handbook, on the other hand, has a somewhat different purpose. A guide would "guide" its readers in determining the feasibility of a green roof, planning, and constructing one. A handbook might contain little or no guidance but have lots of reference information about green roofs: associations supporting them, case studies, specifications, vendors, government ordinances, and so on.
But, frankly, the distinction between these two is difficult. And, in terms of format, style, and structure, there is very little difference. The abstract and executive summary have no logical place in a guide or handbook. If you are taking a technical writing course, check with your instructor about whether you still should include an abstract or executive summary.
Primary Research Reports
Primary research report is our name for that kind of report that presents original research data—no matter whether that data was generated in a laboratory or out in the "field." A secondary research report then would be a report (such as the technical background report) that presents information gained largely from printed or online information sources or from other sources such as interviews or direct observation.
You're probably already familiar with this type of report as the "lab report." The contents and organization of this type of report have a basic logic: you present your data and conclusions, but also present information on how you went about the experiment or survey. In other words, you enable the reader to replicate (the fancy scientific word for repeat) your experiment, or at least, visualize quite specifically how you went about it.
One of the examples is an experiment to see whether production of rainbow trout can be increased by varying water temperature. While there is not a one-to-one correspondence between the typical sections in primary research reports and the sections you see in the actual rainbow trout report, you'll find that most of the functions are carried out. Instead of a full paragraph, sometimes all that is needed is a single sentence. And sometimes certain functions are combined into a single sentence.
Contents of primary research reports. To enable readers to replicate your experiment or survey, you provide information like the following (each normally in its own section):
- Introduction—The introduction to the primary research report needs to do what any good introduction to a report needs to do—get readers ready to read the report. It may provide some background, but not more than a paragraph. Common elements, such as background, can be handled in the introduction. If they require a lot of discussion, however, they may need their own sections.
- Problem, background—One of the first things to do, either in the introduction, or in a separate section of its own, is to discuss the situation that has led to the research work. For example, you may have noticed something that contradicts a commonly accepted theory; you may have noticed some phenomenon that has not been studied, and so on. Explain this somewhere toward the beginning of a primary research report.
- Purpose, objectives, scope—Also toward the beginning of this type of report discuss what you intended to do in the research project—what were your objectives? Also, explain the scope of your work—what were you not trying to do?
- Review of literature—After you've established the basis for the project, summarize the literature relevant to it—for example, books, journal articles, and encyclopedias. If you are doing a study on speech recognition software, what articles have already been written on that subject? What do they have to say about the merits of this kind of software? All you do is summarize this literature briefly and enable readers to go have a look at it by providing the full bibliographic citation at the end of your report. In the context of this type of report, the review of literature shows where the gaps or contradictions are in the existing literature.
- Materials, equipment, facilities—Remember that one of your goals in writing this type of report is to enable the reader to replicate the experiment or survey you performed. Key to this is the discussion of the equipment and facilities you used in your research. Describe things in detail, providing brand names, model numbers, sizes, and other such specifications.
- Theory, methods, procedures—To enable readers to replicate your project, you must also explain the procedures or methods you used. This discussion can be step by step: "first, I did this, then I did that...." Theory and method refer more to the intellectual or conceptual framework of your project. These explain why you used the procedures that you used.
- Results, findings, data—Critical to any primary research report is the data that you collect. You present it in tables, charts, and graphs. These can go in the body of your report, or in appendixes if they are so big that they interrupt the flow of your discussion. Of course, some results or findings may not be presentable as tables, charts, or graphs. In these cases, you just discuss it in paragraphs. In any case, you do not add interpretation to this presentation of data. You merely present the data, without trying to explain it.
- Discussion, conclusions, recommendations—In primary research reports, you interpret or discuss your findings in a section separate from the one where you present the data. Now's the time to explain your data, to interpret it. This section, or area of the report, is also the place to make recommendations or state ideas for further research.
- Bibliography—The ideal of the primary research report is built upon or add to the knowledge in a particular area. It's the vehicle by which our knowledge advances for a specific topic. Your primary research report rests on top of all the work done by other researchers on the same topic. For that reason, you must list the sources of information you used or consulted in your project. This list occurs at the end of the report.
As for the organization of a primary research report, the typical contents just listed are arranged in an actual primary research report in just about the same order they were just discussed. Loosely, it is a chronological order. First, you discuss set-up issues such as the problem and objectives, then you discuss the procedures, then the data resulting from those procedures, then your conclusions based upon that data.
Typical format of primary research reports. In most technical-writing courses, you should use a format like the one shown in the chapter on report format. (The format you see in the example starting on page is for journal articles). In a primary research report for a technical-writing course, however, you should probably use the format in which you have a transmittal letter, title page, table of contents, list of figures, and abstracts.
Specifications are descriptions of products or product requirements. They can provide details for the design, manufacture, testing, installation, and use of a product. You typically see specifications in the documentation that comes in the package with certain kinds of products, for example, CD players or computers. These describe the key technical characteristics of the item. But specifications are also written as a way of "specifying" the construction and operational characteristics of a thing. They are then used by people who actually construct the thing or go out and attempt to purchase it. When you write specifications, accuracy, precision of detail, and clarity are critical. Poorly written specifications can cause a range of problems and lead to lawsuits.
Outline and two-column style used to present information in specifications. Graphics, tables, and lists are heavily used, but some details can only be provided through sentences and paragraphs. For these reasons then, specifications have a particular style, format, and organization:
- Make every effort to find out what the specific requirements are for format, style, contents, and organization. If they are not documented, collect a big pile of specifications written by or for your company, and study them for characteristics like those described in the following.
- Use two-column lists or tables to lists specific details. If the purpose is to indicate details such as dimensions, materials, weight, tolerances, and frequencies, regular paragraph-style writing may be unnecessary.
- For sentence-style presentation, use an outline style similar to the one shown in the illustration above. Make sure that each specification receives its own number–letter designation. In sentence-style specifications, make sure each specific requirement has its own separate sentence.
- Use the decimal numbering system for each individual specification. This facilitates cross-referencing.
Graphics and tables used to present information in specifications.
- Use either the open (performance) style or the closed restrictive style, depending on the requirements of the job. In the open or performance style, you can specify what the product or component should do, that is, its performance capabilities. In the closed style, you specify exactly what it should be or consist of.
- Cross-reference existing specifications whenever possible. Various government agencies as well as trade and professional associations publish specifications standards. You can refer to these standards rather than include the actual specifications details.
- Use specific, concrete language that identifies as precisely as possible what the product or component should be or do. Avoid words that are ambiguous—words that can be interpreted in more than one way. Use technical jargon the way it is used in the trade or profession.
- Test your specifications by putting yourself in the role of a bumbling contractor—or even an unscrupulous one. What are the ways a careless or incompetent individual could misread your specifications? Could someone willfully misread your specifications in order to cut cost, time, and thus quality? Obviously, no set of specifications can ultimately be "foolproof" or "shark-proof," but you must try to make them as clear and unambiguous as possible.
- For specifications to be used in design, manufacturing, construction, or procurement, use "shall" to indicate requirements. In specifications writing, "shall" is understood as indicating a requirement. (See the outline-style specifications in the first illustration on specifications for examples of this style of writing.)
- Provide numerical specifications in both words and symbols: for example, "the distance between the two components shall be three centimeters (3 cm)."
- Writing style in specifications can be very terse: incomplete sentences are acceptable as well as the omission of functions words such as articles and conjunctions that are understood.
- Exercise great caution with pronouns and relational or qualifying phrases. Make sure there is no doubt about what words such as "it," "they," "which," and "that" refer to. Watch out for sentences containing a list of two or more items followed by some descriptive phrase—does the descriptive phrase refer to all the list items or just one? In cases like these, you may have to take a wordier approach for the sake of clarity.
- Use words and phrasing that have become standard in similar specifications over the years. Past usage has proven them reliable. Avoid words and phrases that are known not to hold up in lawsuits.
- Make sure your specifications are complete—put yourself in the place of those who need your specifications; make sure you cover everything they will need.
Contents and Organization of Specifications. Organization is critical in specifications—readers need to be able to find one or a collection of specific details. To facilitate the process of locating individual specifications, use headings, lists, tables, and identifying numbers as discussed previously. But a certain organization of the actual contents is also standard:
- General description — Describe the product, component, or program first in general terms—administrative details about its cost, start and completion dates, overall description of the project, scope of the specifications (what you are not covering), anything that is of a general nature and does not fit in the part-by-part descriptions in the following.
- Part-by-part description — In the main body, present specifications part by part, element by element, trade by trade—whatever is the logical, natural, or conventional way of doing it.
- General-to-specific order — Wherever applicable, arrange specifications from general to specific.
Graphics in specifications. In specifications, use graphics wherever they enable you to convey information more effectively. For example, in the specifications for a cleanroom for production of integrated circuits, drawings, diagrams, and schematics convey some of the information much more succinctly and effectively than sentences and paragraphs.
A literature review summarizes what is known about a specific research topic, narrates the milestones of the research history, indicates where current knowledge conflicts, and discusses areas where there are still unknowns.
A literature review can be a standalone document or a component of a primary research report (as discussed previously). Research journals often contain articles whose sole purpose is to provide a literature review. As a component of a research report, a literature review can be as long as a whole chapter in book, only a paragraph in a research article, or as short as a few sentences in an introduction. In all cases, the function of the literature review is the same: to summarize the history and current state of research on a topic.
As you know from the preceding section, a primary research report (such as those in engineering research journals) focuses on a question: for example, the effect of weightlessness on growing vegetables. The literature-review section of that report would summarize what is known about this topic, indicate where current knowledge conflicts, and discuss areas where there are still unknowns.
A well-constructed literature review tells a story. It narrates the key events in the research on a particular question or in a particular area:
- Who were the first modern researchers on this topic? What were their findings, conclusions, and theories? What questions or contradictions could they not resolve?
- What did researchers following them discover? Did their work confirm, contradict, or overturn the work of their predecessors? Were they able to resolve questions their predecessors could not?
You narrate this series of research events in a literature review. You can consider this research as similar to the thesis–antithesis–synthesis process. You start out with a thesis, then along comes an antithesis to contradict it, and eventually some resolution of this contradiction called a synthesis is achieved, which is actually a step forward in the knowledge about that topic. But now the synthesis becomes a thesis, and the process starts all over again.
Hilton Obenzinger of Stanford University in "How to Research, Write, and Survive a Literature Review?" calls this type of literature review a "road map." He identifies several other types, most importantly those that review the methodology of the research as well as or instead the research findings. Obenzinger emphasizes that the literature review is not just a passive summary of research on a topic but an evaluation of the strengths and weaknesses of that research—an effort to see where that research is "incomplete, methodologically flawed, one-sided, or biased." In any case, as the following examples show, a literature review is a discussion of a body of research literature not an annotated bibliography. Notice in the following examples that literature reviews use standard bracketed IEEE textual citation style and end with a bibliography (called "References").
Consider the following excerpt, which shows the beginning of the review of literature, found in "Face Recognition: A Literature Review:"
Face recognition, in additional to having numerous practical applications such as bankcard identification, access control, mug shots searching, security monitoring, and surveillance system, is a fundamental human behavior that is essential for effective communications and interactions among people. A formal method of classifying faces was first proposed in . The author proposed collecting facial profiles as curves, finding their norm, and then classifying other profiles by their deviations from the norm. This classification is multi-modal, i.e., resulting in a vector of independent measures that could be compared with other vectors in a database.
As you can see, the first paragraph establishes the topic and its importance; the second paragraph goes back to the beginning of modern research that provided a foundation for computer-based face recognition. This literature review moves on to the current status of research in this field:
Progress has advanced to the point that face recognition systems are being demonstrated in real-world settings . The rapid development of face recognition is due to a combination of factors: active development of algorithms, the availability of a large databases of facial images, and a method for evaluating the performance of face recognition algorithms.
Notice how this next excerpt describes an important advance in the research on this topic, but then points out its deficiencies:
The literature review of face-recognition research examines many different methods used in computer-based face recognition. For each, it summarizes the method, the results, and the strengths and weaknesses of that method. This example is not so much the thesis-antithesis-synthesis pattern mentioned above but rather a collection of efforts all striving toward a common goal, increased accuracy of computer-based face recognition. Here's how the summary of that process ends in this literature review:
In , a combined classifier system consisting of an ensemble of neural networks is based on varying the parameters related to the design and training of classifiers. The boosted algorithm is used to make perturbation of the training set employing MLP as base classifier. The final result is combined by using simple majority vote rule. This system achieved 99.5% on Yale face database and 100% on ORL face database. To the best of our knowledge, these results are the best in the literatures.
A. S. Tolba, A.H. El-Baz, and A.A. El-Harby, "Face Recognition: A Literature Review." International Journal of Signal Processing, vol. 2, no. 2, 2005