Chapter 4: Document Design
By: David McMurrey
Upon completion of this chapter, readers will be able to do the following:
- Explain and apply the various uses of graphics in technical documents.
- Create and format appropriate graphics for technical documents.
Introduction to Graphics
One of the nice things about technical writing courses is that most of the papers have graphics in them—or at least they should. A lot of professional, technical writing contains graphics—drawings, diagrams, photographs, illustrations of all sorts, tables, pie charts, bar charts, line graphs, flow charts, and so on. Once you get the hang of putting graphics like these into your writing, you should consider yourself obligated to use graphics whenever the situation naturally would call for them.
Unlike what you might fear, producing graphics is not such a terrible task—in fact, it's fun. You don't have to be a professional graphics artist or technical draftsperson to get graphics into your technical writing. The Internet has advanced our sources for graphics immensely. And, if you are still living the 1970s, you can produce professional-looking graphics with tape, scissors, white-out, and a decent photocopying machine.
Before getting into details on creating, formatting, and incorporating graphics, consider the types and their functions. You can use graphics to represent the following elements in your technical writing:
- Objects—If you're describing a fuel-injection system, you'll probably need a drawing or diagram of the thing. If you are explaining how to graft a fruit tree, you'll need some illustrations of how that task is done. Photographs, drawings, diagrams, and schematics are the types of graphics that show objects.
- Numbers—If you're discussing the rising cost of housing in Austin, you could use a table with the columns marking off five-year periods since 1970; the rows could be for different types of housing. You could show the same data in the form of bar charts, pie charts, or line graphs. Tables, bar charts, pie charts, and line graphs are some of the principal ways to show numerical data.
- Concepts—If you want to show how your company is organized, the relationships of the different departments and officials, you could set up an organization chart—boxes and circles connected with lines that show how everything is hierarchically arranged and related. A concept graphic shows nonphysical, conceptual things and their relationships. In the figure below, see how Apple Computer illustrated the difference between 32-bit processors and 64-bit processors (these days, these are called infographics).
- Words—And finally graphics are used to depict words. You've probably noticed how textbooks put key definitions in a box, maybe with a different color. The same can be done with key points or extended examples. Not the sexiest form of graphics, but it still qualifies, and it's good to keep in mind as a useful technique.
Figure 1: Graphic of the difference between 32-bit processors and 64-bit processors from Apple Computer
Drawings, Diagrams, Photos
To depict objects, places, people, and relationships between them, you can use photos, drawings, diagrams, and schematics.
Uses of Illustrations and Photos
In the realm of illustrations and photographs, the types run from minimal detail to maximal. A simple line drawing of how to graft a fruit tree reduces the detail to simple lines representing the hands, the tools, the graft stock, and graft. Diagrams are a more abstract, schematic view of things, for example, a wiring diagram of a clock radio; it hardly resembles the actual physical thing at all. And of course photographs provide the most detail of all. These graphics, supplying gradations of detail as they do, have their varying uses. Here are some examples:
In instructions, simple drawings (often called line drawings) are the most common. They simplify the situation and the objects so that the reader can focus on the key details. In the examples below, you can see a fully detailed photograph and a simplified, labeled diagram. Which would you prefer?
Figure 2: Fully detailed diagram
Figure 3: Simplified, labeled diagram
- In descriptions, you would want to use drawings, but in this case drawings with more detail, such as shading and depth perspectives.
- In feasibility, recommendation, and evaluation reports, photographs are often used. For example, if you are recommending a photocopier, you might want to include photos of the leading contenders.
When you use an illustration in a report, there are several requirements to keep in mind (most of these are shown in this illustration):
Figure 4: Formatting requirements
- Labels—Just about any illustration should contain labels—words and phrases—with pointers to the parts of the things being depicted.
- Keys—If the illustration has certain shadings, colors, line styles, or other such details that have a special meaning in the illustration, these should be indicated in a key—an area in an unused corner of the illustration that deciphers their meaning.
- Titles—Except in special cases, illustrations should have titles, and these titles should be numbered (Figure 1, Figure 2, and so on). The exceptions are these: if you have lots of illustrations (for example, in certain instructions, there are illustrations practically after every paragraph) and if there is no benefit from the titles; if you only have one or two illustrations and they are not cross-referenced; and/or if you do not cross-reference your illustrations. In some of these cases, you might want to keep the title but discard the word "Figure" and the number following it.
- Cross-references—Almost all illustrations should be referred to from the relevant point in the discussion. And, do more than just tossing in a "(See Figure 2)"; discuss the illustration a bit—focus readers' attention on the key details of the illustration.
- Location within the report—Ideally, you place illustrations just after the point where they are needed. However, sometimes because of the pagination (the way the text falls on the pages) and the size of the illustrations, this close placement is not possible. No problem—just put the illustration at the top of the next page; that is what the figure-numbering system is for.
- Size of illustrations—Again, ideally, you want illustrations to be between one-half to one-quarter of the vertical size of the page. You want them to fit on the page with other text. In fact, that's what you really want—to interperse text and graphics in a report. What you do not want is to append the illustration to the back of the report! When you have a large illustration, use your software or a photocopier to reduce it.
- Placement within margins—Make sure that your illustrations fit neatly and comfortably within standard margins. You don't want the illustration spilling over into the right or left margins. You want to allow the equivalent of at least one blank line above and below the illustration.
- Level of technical detail—And, rather obviously, you want illustrations to be at the right technical level for your readers. No chip circuitry diagrams for computer beginners!
Now for the question we're all waiting to ask—how to create graphics? There are several options: scanning, photocopying, using computer graphics, and hand-drawing. In all of these production methods, don't forget that you must indicate the source of the borrowed graphic.
Scanning is the best way to pull graphics into your document files. Scanners are quite affordable now, especially those that include printing and faxing capabilities. Universities and colleges usually make scanners available to students and faculty. Print shops will scan for a fee. You copy your graphics to graphic-format files (such as .jpg or .png) then copy them into your document files.
Note: When you scan a graphic, trim off the title (caption) and other material from the original. Replace this material with words of your own.
- Photocopying used to be the method. You photocopied graphics from print sources, trimmed them, left room for them as you typed text (yes, with a typewriter), taped in the photocopies, and photocopied the whole document. Done well, the result could look almost professional.
- Using computer graphics With a little practice, you can create graphics like the ones show in the figure here in OpenOffice Writer or Microsoft Word (and of course GIMP and Illustrator). With a computer-graphics drawing like the keylock mechanism to the right, you are at the very edge of what OpenOffice Writer or Microsoft Word can do.
- Hand-drawing may not be as out of the question as you might think. Take a blank sheet of paper and start sketching lightly with a soft-leaded pencil. Keep working until you have the drawing the way you like. Then use a black marker to ink in the lines that you want, and erase the stray pencil markings. Now, scan this drawing and follow the method described above.
Figure 8: Illustrated graphic
Documenting Graphics: Indicating Sources
As mentioned earlier, it's perfectly legal to borrow graphics—to trace, photocopy, scan, or extract subsets of data from them. But you're obligated to cite your sources for graphics just as you are for the words you borrow. Normally, this is done in the figure title of the graphics.
Guidelines for Graphics: A Review
The preceding sections state a number of common guidelines that need to be stated all in one place. These are important!
- Use graphics whenever they would normally be necessary—don't wimp out because it seems like too much trouble! But at the same time, don't get hung up about creating perfect graphics (scans and photocopies work just fine for our purposes as long as you cite your source). This course is a writing course, not a graphic-arts course.
- Always discuss graphics in nearby text preceding the graphic. Don't just throw a graphic out there unexplained. Orient readers to the graphic; explain its basic meaning.
- If a certain graphic is difficult to produce, discuss the problem with your instructor (you might be able to leave a blank with a descriptive note in the middle).
- Make sure your graphics are appropriate to your audience, subject matter, and purpose—don't zap beginners with advanced, highly technical graphics they can't understand.
- Intersperse graphics and text on the same page. Don't put graphics on pages by themselves; don't attach them to the end of documents.
- Use figure titles for graphics (see the exceptions to this rule in the preceding).
- Indicate the source of any graphic you have borrowed—this includes tables, illustrations, charts, and graphs. Whenever you borrow a graphic from some other source, document that fact in the figure title.
- Include identifying detail such as illustration labels, axis labels, keys, and so on. For labels, use text boxes and turn off the borders.
- Make sure graphics fit within normal margins—if they don't, enlarge or reduce the copies. Leave at least one blank line above and below graphics.
- This guideline is for folks still operating in the 1970s. When you tape graphics in to your report, photocopy your entire report, not just the pages on which the tape-ins occur. Hand in the entire photocopied document, not the original and not a mixture of original and photocopied pages. Don't manually add color or other detail on the pages of the final copy that you intend to submit—in other words, don't draw on the final copy. Any details like these should be added before photocopying. If you must have color, use color photocopying equipment.
- Place graphics as near to the point in the text where they are relevant as is reasonable. However, if a graphic does not fit properly on one page, put it at the top of the next, and continue with regular text on the preceding page. Don't leave half a page blank just to keep a graphic near the text it is associated with.
- Cross-reference all graphics from the appropriate text. In the cross-reference, give the figure number (if one is used), indicate the subject matter of the graphic, and provide explanatory information as necessary.