Technical documents (including handbooks, white papers and guides) have various designs depending on the industry, profession, or organization. This chapter shows you one traditional design. If you are taking a technical writing course, make sure the design presented in this chapter is acceptable. The same is true if you are writing a technical document in a science, business, or government context.
Note: For years this online technical writing textbook generically referred to reports as practically anything containing technical information. But because "report" refers to a specific genre of technical document, the change had to be made to the generic "techdoc," short for technical document.
Techdocs (generic name for technical documents) have specifications as do any other kind of project. Specifications for techdocs involve layout, organization and content, format of headings and lists, the design of the graphics, and so on. The advantage of a required structure and format for techdocs is that you or anyone else can expect them to be designed in a familiar way—you know what to look for and where to look for it. Techdocs are usually read in a hurry—people are in a hurry to get to the information they need, the key facts, the conclusions, and other essentials. A standard techdoc format is like a familiar neighborhood.
When you analyze the design of a techdoc, notice how repetitive some sections are. This duplication has to do with how people read techdocs. They don't read techdocs straight through: they may start with the executive summary, skip around, and probably not read every page. Your challenge is to design techdocs so that these readers encounter your key facts and conclusions, no matter how much of the techdoc they read or in what order they read it.
Be sure and see the example techdocs.
The standard components of the typical technical report are discussed in this chapter. The following sections guide you through each of these components, pointing out the key features. As you read and use these guidelines, remember that these are guidelines, not commandments. Different companies, professions, and organizations have their own varied guidelines for techdocs—you'll need to adapt your practice to those as well the ones presented here.
Letter of Transmittal
The transmittal letter is a cover letter, either attached to the outside of the techdoc with a paper clip or bound within the techdoc. It is a communication from you—the techdoc writer—to the recipient, the person who requested the techdoc and who may even be paying you for your expert consultation. Essentially, it says "Okay, here's the techdoc that we agreed I'd complete by such-and-such a date. Briefly, it contains this and that, but does not cover this or that. Let me know if it meets your needs." The transmittal letter explains the context—the events that brought the techdoc about. It contains information about the techdoc that does not belong in the techdoc.
In the example of the transmittal letter in the following, notice the standard business-letter format. If you write an internal techdoc, use the memorandum format instead; in either case, the contents and organization are the same:
First paragraph. Cites the name of the techdoc, putting it in italics. It also mentions the date of the agreement to write the techdoc.
Middle paragraph. Focuses on the purpose of the techdoc and gives a brief overview of the techdoc's contents.
Final paragraph. Encourages the reader to get in touch if there are questions, comments, or concerns. It closes with a gesture of good will, expressing hope that the reader finds the techdoc satisfactory.
As with any other element in a techdoc, you may have to modify the contents of this letter (or memo) for specific situations. For example, you might want to add another paragraph, listing questions you'd like readers to consider as they review the techdoc.
Covers, Title Page and Label
If your techdoc is over ten pages, bind it in some way and create a label for the cover.
Covers
Covers give techdocs a solid, professional look as well as protection. You can choose from many types of covers. Keep these tips in mind:
- Totally unacceptable are the clear (or colored) plastic slip cases with the plastic sleeve on the left edge. These are like something out of freshman English; plus they are aggravating to use—readers must struggle to keep them open and hassle with the static electricity they generate.
- Marginally acceptable are the covers for which you punch holes in the pages, load the pages, and bend down the brads. If you use this type, leave an extra half-inch margin on the left edge so that readers don't have to pry the pages apart. Of course, this type of cover prevents pages from lying flat: readers must grab available objects or use various body parts to keep the pages weighted down.
- By far the best covers are those that allow techdocs to lie open by themselves (see the illustration in the next section). What a great relief for a techdoc to lie open in your lap or on your desk. This type uses a plastic spiral for the binding and thick, card-stock paper for the covers. Check with your local copy shop for these types of bindings; they are inexpensive and add to the professionalism of your work. See the simulated example of a plastic spiral bnding in the following.
Generally less preferable are loose-leaf notebooks, or ring binders. These are too bulky for short techdocs, and the page holes tend to tear. Of course, the ring binder makes changing pages easy; if that's how your techdoc will be used, then it's a good choice. At the "high end" are the overly fancy covers with their leatherette look and gold-colored trim. Avoid them—keep it plain, simple, and functional.
Title Page
At its simplest, a techdoc title is a copy of what's on the front cover—possibly with a few details added.
Take a look at the title page Abstract and Executive Summary.
Labels
Be sure to devise a label for the cover of your techdoc. It's a step that some techdoc writers forget. Without a label, a techdoc is anonymous; it gets ignored.
The best way to create a label is to use your word-processing software to design one on a standard page with a graphic box around the label information. Print it out, then go to a copy shop and have it photocopied directly onto the techdoc cover.
Not much goes on the label: the techdoc title, your name, your organization's name, a techdoc tracking number, and a date. There are no standard requirements for the label, although your company or organization should have its own requirements. (An example of a techdoc label is shown below.)
Transmittal letter and techdoc cover (with cover label).
Abstract and Executive Summary
Most technical techdocs contain at least one abstract—sometimes two, in which case the abstracts play different roles. Abstracts summarize the contents of a techdoc, but the different types do so in different ways:
- Descriptive abstract. This type provides an overview of the purpose and contents of the techdoc. In some techdoc designs, the descriptive abstract is placed at the bottom of the title page, as shown in the following:
Descriptive abstract. Traditionally, it is placed on the title page (not the cover page). - Executive summary. Another common type is the executive summary, which also summarizes the key facts and conclusions contained in the techdoc. See the example shown in the following. It's as if you used a yellow highlighter to mark the key sentences in the techdoc and then siphoned them all out onto a separate page and edited them for readability. Typically, executive summaries are one-tenth to one-twentieth the length of techdocs ten to fifty pages long. For longer techdocs, ones over fifty pages, the executive summary should not go over two pages. The point of the executive summary is to provide a summary of the techdoc—something that can be read quickly.
If the executive summary, introduction, and transmittal letter strike you as repetitive, remember that readers don't necessarily start at the beginning of a techdoc and read page by page to the end. They skip around: they may scan the table of contents; they usually skim the executive summary for key facts and conclusions. They may read carefully only a section or two from the body of the techdoc, and then skip the rest. For these reasons, techdocs are designed with some duplication so that readers will be sure to see the important information no matter where they dip into the techdoc.
Table of Contents
You're familiar with tables of contents (TOC) but may never have stopped to look at their design. The TOC shows readers what topics are covered in the techdoc, how those topics are discussed (the subtopics), and on which page numbers those sections and subsections start.
In creating a TOC, you have a number of design decisions:
- Levels of headings to include. In longer techdocs, consider including only the top two levels of headings. This keeps the TOC from becoming long and unwieldy. The TOC should provide an at-a-glance way of finding information in the techdoc quickly.
- Indentation, spacing, and capitalization. Notice in the illustration below that items in each of the three levels of headings are aligned with each other. Although you can't see it in the illustration, page numbers are right-aligned with each other. Notice also the capitalization: Main chapters or sections are all caps; first-level headings use initial caps on each main word; lower-level sections use initial caps on the first word only.
- Vertical spacing. Notice that the first-level sections have extra space above and below, which increases readability.
One final note: Make sure the words in the TOC are the same as they are in the text. As you write and revise, you might change some of the headings—don't forget to change the TOC accordingly. See the example of a table of contents:
Table of contents (which comes first) then the executive summary. This TOC uses decimal-numbering style for the chapter and section numbers, which is common in techdocs. Others in this book use the uppercase roman-numeral style for the top-level chapters only (see DVD techdoc).
List of Figures and Tables
The list of figures has many of the same design considerations as the table of contents. Readers use the list of figures to find the illustrations, diagrams, tables, and charts in your techdoc.
Complications arise when you have both tables and figures. Strictly speaking, figures are illustrations, drawings, photographs, graphs, and charts. Tables are rows and columns of words and numbers; they are not considered figures.
For longer techdocs that contain dozens of figures and tables each, create separate lists of figures and tables. Put them together on the same page if they fit, as shown in the illustration below. You can combine the two lists under the heading, "List of Figures and Tables," and identify the items as figure or table as is done in the illustration below.
Introduction
An essential element of any techdoc is its introduction—make sure you are clear on its real purpose and contents. In a techdoc, the introduction prepares the reader to read the main body of the techdoc. See introductions for a discussion of writing introductions.
See this example of an introduction:
List of figures and tables followed by the introduction. If there are no tables, make it "List of Figures." In a technical writing course, ask your instructor if the decimal-numbering style for headings is required.
Body of the Techdoc
The body of the techdoc is of course the main text of the techdoc, the sections between the introduction and conclusion. Illustrated below are sample pages.
Headings
In all but the shortest techdocs (two pages or less), use headings to mark off the different topics and subtopics covered. Headings enable readers to skim your techdoc and dip down at those points where you present information that they want. See headings for guidelines on headings.
Bulleted and Numbered Lists
In the body of a techdoc, also use bulleted, numbered, and two-column lists where appropriate. Lists help by emphasizing key points, by making information easier to follow, and by breaking up solid walls of text. See lists for guidelines on lists.
Symbols, Numbers, and Abbreviations
Technical discussions ordinarily contain lots of symbols, numbers, and abbreviations. Remember that the rules for using numerals as opposed to words are different in the technical world. The old rule about writing out all numbers below 10 does not always apply in technical techdocs. (See numbers vs words for guidelines.)
Except from the body of a techdoc. In a technical writing course, ask your instructor if the decimal-numbering style for headings is required. Also, a different documentation system may be required—not the IEEE, which is for engineers.
Graphics and Figure Titles
In technical , you're likely to need drawings, diagrams, tables, and charts. These not only convey certain kinds of information more efficiently but also give your techdoc an added look of professionalism and authority. If you've never put these kinds of graphics into a , there are some relatively easy ways to do so—you don't need to be a professional graphic artist. For strategies for adding graphics to s, see graphics. For strategies for adding tables to s, see tables.
Cross-References
You may need to point readers to closely related information within your , or to other books and techdocs that have useful information. These are called cross-references. For example, they can point readers from the discussion of a mechanism to an illustration of it. They can point readers to an appendix where background on a topic is given (background that just does not fit in the text). And they can point readers outside your techdoc to other information—to articles, techdocs, and books that contain information related to yours. When you create cross-references, follow these guidelines presented in cross-references.
Conclusions
For most techdocs, you'll need to include a final section. When you plan the final section of your techdoc, think about the functions it can perform in relation to the rest of the techdoc. Ideas for final sections are presented in conclusions.
Appendixes
Appendixes are those extra sections following the conclusion. What do you put in appendixes?—anything that does not comfortably fit in the main part of the techdoc but cannot be left out of the techdoc altogether. The appendix is commonly used for large tables of data, big chunks of sample code, fold-out maps, background that is too basic or too advanced for the body of the techdoc, or large illustrations that just do not fit in the body of the . Anything that you feel is too large for the main part of the techdoc or that you think would be distracting and interrupt the flow of the techdoc is a good candidate for an appendix. Notice that each one is given a letter (A, B, C, and so on).
Information Sources
Documenting your information sources is all about establishing, maintaining, and protecting your credibility in the profession. You must cite ("document") borrowed information regardless of the shape or form in which you present it. Whether you directly quote it, paraphrase it, or summarize it—it's still borrowed information. Whether it comes from a book, article, a diagram, a table, a web page, a product brochure, an expert whom you interview in person—it's still borrowed information.
Documentation systems vary according to professionals and fields. Engineers use the IEEE system, examples of which are shown throughout this chapter. Another commonly used documentation system is provided by the American Psychological Association (APA). See documentation for details.
Page Numbering
Page-numbering style used in traditional techdoc design differs from contemporary techdoc design primarily in the former's use of lowercase roman numerals in front matter (everything before the introduction).
- All pages in the techdoc (within but excluding the front and back covers) are numbered; but on some pages, the numbers are not displayed.
- In the contemporary design, all pages throughout the document use arabic numerals; in the traditional design, all pages before the introduction (first page of the body of the ) use lowercase roman numerals.
- On special pages, such as the title page and page one of the introduction, page numbers are not displayed.
- Page numbers can be placed in one of several areas on the page. Usually, the best and easiest choice is to place page numbers at the bottom center of the page (remember to hide them on special pages).
- If you place page numbers at the top of the page, you must hide them on chapter or section openers where a heading or title is at the top of the page.
Note: Longer techdocs often use the page-numbering style known as folio-by-chapter or double-enumeration (for example, pages in Chapter 2 would be numbered 2-1, 2-2, 2-3, and so on). Similarly, tables and figures would use this numbering style. This style eases the process of adding and deleting pages.
I would appreciate your thoughts, reactions, criticism regarding this chapter: your response—David McMurrey.
