12: Visuals in Technical Documents
- Page ID
- 89518
- Explain the various types of visuals in technical documents and their uses.
- Identify and apply best practices when selecting and creating tables, charts, graphs, lists, callouts, and images for use in business documents.
- Describe the appropriate format and use of visuals in technical documents.
Introduction
One of the nice things about technical writing courses is that many of the assignments have graphics in them—or at least they should. Professional writing often contains graphics—drawings, diagrams, photographs, illustrations, tables, pie charts, bar charts, line graphs, flow charts, and so on. Graphics are an important feature of technical communication.
We learn more from a document when graphics are included (Gatlin, 1988). In fact, people learn about 1/3 more from a document with graphics than without (Levie and Lentz, 1982). A recent study found that readers learn faster and are better able to use the information they learn when the text includes graphics (Große, Jungmann, and Drechsler, 2015). That does not, of course, mean that one should place graphics willy-nilly into every spot possible, nor should they be treated as mere decoration. On the contrary, graphics should be used carefully and correctly. The information below will help you make informed decisions regarding graphic creation and placement in order to improve the readability of your documents.
Overview
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 writing:
- Objects—If you're describing a fuel-injection system, you'll probably need a drawing or diagram of the component parts. 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 in an infographic.
- Words—Finally, graphics can be 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 draw attention to key points or extended examples.
Tables
Tables are rows and columns of numbers and words, mostly numbers. They permit rapid access to and relatively easy comparison of information. If the data is arranged chronologically (for example, sales figures over a ten-year period), the table can show trends—patterns of rising or falling activity. Of course, tables are not necessarily the most vivid or dramatic means of showing such trends or relationships between data—that's why we have charts and graphs (discussed in the next section).
Uses for Tables
The most common use of tables is to share numerical data. Imagine that you are comparing different models of laser printers in terms of physical characteristics, such as height, depth, length, weight, and so on. This type of information is perfect for a table.
However, don't get locked into the notion that tables are strictly for numbers. Whenever you have situations where you discuss several things about which you provide the same categories of detail, you've got the possibility to use a table. Again, imagine that you are comparing several models of a laser printer, but you want to know more detailed information about things like its cost, print speed, supply costs, and warranty terms. This is an ideal opportunity to use a table, and it would be mostly words rather than numbers (and in this case, you would probably want to leave the textual discussion where it is and "re-present" the information in table form).
Formatting Requirements
In its simplest form, a table is a group of rows and columns of data. At the top of each column is a column heading, which defines or identifies the contents of that column (and indicates the unit of measurement when applicable). On the left edge of the table may be row headings, which define or identify the contents of that row. Things get tricky when rows or columns must be grouped or subdivided. In such cases, you have to create row or column subheadings. This situation is illustrated in the table below:
Traditionally, the title of a table is placed on top of the table or is the first row of the table. If the contents of the table are obvious and there is no need to cross-reference the table from anywhere else in the report, you can omit the title.
When formatting tables for a business document, keep the following guidelines in mind:
- Refer to the table in the text just preceding the table. Explain the general significance of the data in the table; don't expect readers to figure it out entirely for themselves.
- Don't overwhelm readers with an enormous 11-column, 30-row tables. Simplify the table data down to just that amount of data that illustrates your point while making sure that this does not distort or misrepresent the data.
- Don't put the word or abbreviation for the unit of measurement in every cell of a column. For example, in a column of measurements all in millimeters, don't put "mm" after every number. Put the abbreviation in parentheses in the column or row heading.
- Right- or decimal-align numbers in the columns. If the numbers 123 and 4 were in the same column, the 4 should appear right below the 3, not the 1.
- Normally, words in columns are left-justified (although you will occasionally see columns of words all centered).
- When there is some special point you need to make about one or more of the items in the table, use a footnote instead of clogging up the table with the information.
Producing Tables
When conducting research, you may find data in a table that you wish to incorporate into your own work. If it's a simple table without too many rows and columns, you can retype it yourself into your own document (but remember to document where the data came from in the figure title). However, if it is a large table with lots of data, you're justified in scanning, screen-capturing, or photocopying it and bringing it into your report that way.
Occasionally, in report drafts, information is presented in regular running-text form that could be better presented in table (or tabular) form. Be sure and look back over your rough drafts for material that can transform into tables.
Charts and Graphs
Charts and graphs are another way of presenting the same numeric data that is presented in tables, although a more dramatic and visually interesting one. At the same time, however, you get less detail and precision in a chart or graph than you do in a table. Imagine the difference between a table of sales figures for a ten-year period and a line graph for that same data. You can convey a better sense of the overall sales trend by using a graph, but it may be harder to decipher a single, precise dollar amount than it would be in a table.
Formatting Requirements
When you create charts and graphs, keep these formatting tools in mind:
- Axis labels. In bar charts and line graphs, don't forget to indicate what the x and y axes represent. One axis might indicate millions of dollars; the other, five-year segments from 1960 to the present.
- Keys (legends). Bar charts, line graphs, and pie charts often use special color, shading, or line style (solid or dashed). Be sure to indicate what these mean; translate them in a key in some unused place in the chart or graph.
- Figure titles. Charts and graphs must include a title. In many cases, this will be a numbered figure, as seen throughout this chapter. Readers need some way of knowing what they are looking at.
- Cross-references. Whenever you use a chart or graph, put a cross-reference to it from the related text. With that cross-reference, provide some explanation of what is going on in the graphic, how to interpret it, what its basic trends are, and so on.
- Documentation. When you borrow information to create a graphic, use the APA format to indicate the source. It does not matter how you import the graphic into your report—it is all borrowed information, which some brave and noble soul worked hard to develop and who deserves credit for that effort.
Producing Charts and Graphs
As with tables, you can screen-capture, scan, or photocopy charts and graphs that you find to use in your work. You can also generate your own graphics with many types of software. Familiarize yourself with the table-generating tools in your word processing program since they will be able to draw the lines and create other formatting details automatically. Free charting and graphing tools are also available online if you want even more design control. Some helpful resources for creating your own charts and graphs include:
Drawings, Diagrams, and Photos
To depict objects, places, people, and relationships between them, you can use photos, drawings, and diagrams.
Uses of Illustrations and Photos
In the realm of illustrations and photographs, examples used in business documents can 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 hardly resembles the actual physical thing at all. Photographs provide the most detail of all. These graphics, supplying gradations of detail as they do, have 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 of a microprocessor alongside a simplified, labeled diagram of one. In this circumstance, the diagram has less visual distraction, making it more helpful to the person carrying out the task.
- In descriptions, you want to use drawings, but in this case drawings with more detail that show shading and depth perspectives, or employ techniques that display key features, as in a map, a floor plan, a cross-section, or an exploded view.
- Photographs are often used in feasibility, recommendation, and evaluation reports. Since photographs are a precise representation of the object depicted, they are useful tools when accuracy is important. For example, if you are recommending a photocopier, you might want to include photos of the leading contenders.
Formatting Requirements
When you use an illustration in a report, there are several design considerations to keep in mind, a number of which can be seen in the illustration below:
- Labels. Just about every illustration should contain labels—words and phrases with pointers to the parts of the objects 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. Illustrations should have specific titles that briefly describe the image, and these titles should be numbered (Figure 1, Figure 2, and so on). If there is only one graphic element in the document, the title may be omitted.
- Cross-references. Illustrations should be referred to at the relevant point in the discussion. Identify the figure by its number, and discuss the illustration a bit—focus readers' attention on the key details of the illustration.
- Location within the report. Ideally, illustrations should be placed 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. When this happens, just put the illustration at the top of the next page.
- Size of illustrations. Illustrations should be between one-half to one-quarter of the vertical size of the page, and should fit on the page with other text. In fact, that's what you really want—to intersperse text and graphics in a report. Avoid appending the illustration to the back of the report; if your reader has to go searching for it, the image will not be as useful.
- 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. Allow the equivalent of at least one blank line above and below each illustration.
- Level of technical detail. Illustrations should be at the appropriate technical level for your readers. Remember to be mindful of your audience when creating and selecting images.
Producing Illustrations
Technology has made capturing and manipulating images easier than ever, and most computers and smartphones come equipped with basic photo editing tools. Digital clip art and stock photography are also readily available on from a number of websites. Even if you are not taking and editing your own pictures or using existing digital images, there are still several options available: scanning, using computer graphics software, and hand-drawing. No matter which method you choose, don't forget that you must indicate the source of any borrowed graphics.
- Scanning is the best way to pull graphics from printed materials into your document files. Universities and colleges usually make scanners available to students and faculty. Print shops will allow you to scan for a fee. Save your graphics as 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.
- Using computer graphics software has become more user-friendly in recent years. With a little practice, you can create graphics like the ones shown in the figure below in OpenOffice Writer or Microsoft Word (and of course GIMP and Illustrator). With a computer-graphics drawing like the keylock mechanism in Figure 9, you are at the very edge of what OpenOffice Writer or Microsoft Word can do.
- Drawing images by hand is also an option. You can trace shapes to get rough images to start, then sketch over this 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, erasing any stray pencil markings. Once the drawing is complete, just scan the image following the method described above.
Indicating Sources
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, but an instructor may want images credited on your references page as well, so always check the assignment for any such requirements.
- Intersperse graphics and text on the same page. 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.
- Watch out for areas in your text where you discuss lots of numeric data in relation to two or more things—that's ideal for tables, charts, or graphs.
- Watch out for areas in your text where you define a series of terms—that's ideal for tables.
- Always discuss visuals in the preceding text. Don't just place a table, chart, graph, or image in your document without explanation. Orient readers to it and explain its significance.
- Make sure your visuals are appropriate to your audience, subject matter, and purpose—don't overwhelm beginners with massive, highly technical constructions they can't understand.
- Label all visuals with appropriate identifying information: column and row headings, keys, axis labels, and so on.
- Use a title unless the table, chart, or graph is very informal. Remember that the title goes just above the table; for charts and graphs, below.
- Indicate the source of all visuals you have borrowed whether in part or in whole. This can be done in the figure title or in a footnote.
Labels and Callouts
To identify specific elements or features, place labels and captions directly on or close to the graphic. Although the terms are used interchangeably, labels are text identifiers that are self-explanatory in an image, while callouts are labels that require further information outside the image to explain what they are identifying" (Lannon & Gurak, 2019). They supplement the visual information. But use them selectively; use them only if readers need them (Rude & Eaton, 2010).
The advantage of labels is that the reader gains a basic understanding of elements in the graphic without referring to supplementary explanations. But, too many labels obscure the image. In this case, callouts are the better option. Use numbers or letters to identify each element and the supplementary explanations.
1. Determine the number of items to identify in the image (Lannon & Gurak, 2019).
2. Estimate how much explanation each item requires to determine if labels or callouts are more appropriate (Lannon & Gurak, 2019).
3. When writing labels and callouts,
- create a consistent visual style (Lannon & Gurak, 2019)
- use the same terms on the label or callout as in the text (Rude & Eaton, 2010)
- in general, all parts mentioned in the text should have a label or callout, and all parts with a label or callout should be mentioned in the text. (Rude & Eaton, 2010)
- Layout the labels or callouts next to the elements in the graphic they identify, using a line to connect the two, if necessary.
- Use a standard font and size for readability (Rude & Eaton, 2010)
- Align the labels and callouts for a neater appearance (Rude & Eaton, 2010)
- If callouts are used, place the explanatory text in a key next to the graphic.
Labels
Labels can take different forms (Lannon & Gurak, 2019):
- They may be placed directly on the graphic (whereby they become part of the graphic).
- They may be placed around the graphic and use lines to point to the relevant element in the graphic.
- Online, labels can be links or hotspots whereby more information about the element is displayed on mouse rollover.
1. This map of Central Park, New York is an example of labels placed directly on the graphic.
2. In the following example, the labels are placed around the graphic.
3. In the following example, Anatomy of a Steam Locomotive, when the mouse is rolled over the 'Firebox' label, the text will read: "Literally a box containing the fire. It is surrounded by water on the top and all sides. The bottom is a grate with an ash pan below that.”
Callouts
Callouts are best used when many parts of the image need to be labeled and each part requires a longer explanation. In fact, the label sequence may be in alphabetical or numerical (as in Figure 15.36) order. Ensure that the explanation is near the graphic
Note: Coded callouts are in numerical sequence; the explanation for each number appears below the graphic. The example above shows part of the explanation of Number 1 explanation only.
Captions
Captions, tables, and graphics titles must clearly identify information to the reader. Interpretive captions usually require one or more sentences. Captions should be informational, without becoming too lengthy. Captions that are merely a title for a graphic are not very helpful (Covey, 2012).
Writing Style for Captions
- Captions for graphics include the title and any explanatory material, immediately under the graphic.
- Words such as Figure, Illustration, and Table should be in bold type.
- The caption should be italicized.
- Treat tables and figures the same.
Good captions are what guide readers not only to see but also to understand. Captions label graphics with titles and explain to readers what they are seeing, and how to interpret the information captured in the visual. The Franklin Covey Style Guide for Business and Technical Communication provides an excellent source for writing captions (Covey, 2012).
- Use interpretive captions whenever possible. Interpretive captions provide both a title and explanatory information, usually expressed in a complete sentence, to help readers understand the central point(s) that the writer wants to convey. A graphic and its caption should be clear and understandable without requiring readers to search for clarifying information in the text:
Examples:
Figure 4. Cabin-Temperature Control System. Constant cabin temperature control is maintained by the system's modulated cabin sensor.
This interpretive caption gives the title and then tells the reader the principal message - that the check valve provides near-zero risk. And, it states how the check valve provides near-zero risk (Covey, 2012).
Figure 23. Check Valve. The risk of bad air entering the changer is near zero because the check valve permits airflow in one direction only.
This interpretive caption gives the title of the figure and emphasizes that the cabin has a constant temperature - a benefit provided by the feature described in the figure. The caption states clearly what the writer wants the reader to learn from the drawing (Covey, 2012).
- Avoid using short, often ambiguous, titles to replace interpretive captions. In the past, styles for technical and scientific documents used only short, simple title captions for visuals. These were often superfluous, providing no real information other than the obvious to the reader, i.e. - A Horse. Titles that are so short and cryptic that they sound telegraphic are not useful. Such captions are only useful when the graphics are self-explanatory and require no interpretation (Covey, 2012).
- Number figures and tables sequentially throughout the document, and place the number before the caption. If an important figure or table is presented twice, treat it as two separate visuals and number each. Figure and table numbers should be whole numbers (Covey, 2012).
- Use periods following interpretive captions but no punctuation following short captions that are not sentences. Interpretive captions are usually complete sentences and should therefore end with a period. Short captions, like titles and headings, are not usually complete sentences, so they require no punctuation (Covey, 2012).
- Captions may appear below or above a visual, but consistency throughout a document is critical. Arguments support both options; choose one, warrant your choice, and be consistent.
- Put the caption above the visual for better visibility when captions are used with slides and other project visual aids. Captions placed at the bottom may be blocked by the heads of those seated in front (Covey, 2012). Captions may appear below or above a visual, but consistency throughout a document is critical. Arguments support both options; choose one, warrant your choice, and be consistent.
Note: Notes or footnotes are categorized as either explanatory or source notes. Explanatory footnotes are identified by a superscript number or letter. The order in which notes appear is important; explanatory footnotes are placed above source notes. And both are placed above the caption if the caption is placed at the bottom of the illustration, as show in the following example:
Lists
Lists are useful because they emphasize selected information in regular text. When you see a list of three or four items strung out vertically on the page rather than in normal paragraph format, you naturally notice it more and are likely to pay more attention to it. Certain types of lists also make for easier reading. For example, in instructions, it is a big help for each step to be numbered and separate from the preceding and following steps. Lists also create more white space and spread out the text so that pages don't seem like solid walls of words.
Like headings, the various types of lists are an important feature of professional technical writing: they help readers understand, remember, and review key points; they help readers follow a sequence of actions or events; and they break up long stretches of straight text.
Your task for this chapter is to learn about the different types and uses of lists and to learn their specific format and style.
General Guidelines
In professional technical-writing contexts, you must use a specific style of lists, like the one presented here.
- Use lists to highlight or emphasize text or to enumerate sequential items.
- Use exactly the spacing, indentation, punctuation, and caps style shown in the following discussion and illustrations.
- Make list items parallel in phrasing.
- Make sure that each item in the list reads grammatically with the lead-in.
- Use a lead-in to introduce the list items and to indicate the meaning or purpose of the list (and punctuate it with a colon).
- When two items are alternatives, use a bulleted list (with or between). Do not use numbered lists for items connected by or. Booleans would call these ORed items. Indicate this OR relationship in the list lead-in.
- When a separate notice or explanatory paragraph follows an item, indent that separate material to the text of the parent list item.
Example: Intented material
Figure 15.15. Indented material that elaborates on the parent list item.
- Avoid using headings as lead-ins for lists.
- Avoid overusing lists; using too many lists destroys their effectiveness.
- Use similar types of lists consistently in similar text in the same document. For example, if you have two areas of text that present steps for doing a task, both should use the same list format—in this case, numbered lists.
- Use the "hanging indent" format for list items two or more lines long. This format is illustrated in the section on hanging indents.
- Use the "styles" function in your software to create vertical lists rather than constructing them manually. See this brief tutorial on using styles for lists.
Note: In-sentence lists could be called "horizontal" lists. All the other list types presented here are "vertical" lists in that they format the items vertically rather than in paragraph format.
Specific Types of Lists Guidelines
It's difficult to state guidelines on choosing between the various kinds of lists, but here's a stab at it:
- Most importantly, use numbered lists for items that are in a required order (such as step-by-step instructions) or for items that must be referred to by item number. Use bulleted lists for items that are in no required order.
- With in-sentence lists, there are no conventions when to use letters (a), (b), and so on, as opposed to numbers (1), (2), and so on. If you are in a numbered list and need a sublist, use lowercase letters, to contrast with the numbers. Otherwise, there seem to be no widely agreed-upon guidelines—just be consistent!
- Use vertical lists as opposed to in-sentence lists when you want the emphasis provided by the vertical presentation. In-sentence lists provide only minimal emphasis; vertical lists provide much more.
- Within an individual report, use in-sentence lists and vertical lists consistently for similar situations. For example, if you have topic overviews for each section of a report, use in-sentence or vertical lists for the overview—but don't mix them for that particular use.
Common Problems with Lists
Problems with lists usually include the following:
- Mix-up between numbered and bulleted lists
- Lack of parallel phrasing in the list items
- Use of single parentheses on the list-item number or letter (in other words, 1) or (1)
- Run-over lines not aligned with the text of list items
- Lack of a strong lead-in sentence introducing list items, and lack of a colon to punctuate lead-ins
- Inconsistent caps style in list items
- Unnecessary punctuation of list items
- Inconsistent use of lists in similar text
- Lists that have too many items and need to be subdivided or consolidated
Format for Lists
Use the following for specific details on the capitalization, typography (bold, underlining, different fonts, different types sizes), and spacing for each type of list.
In-sentence lists
Use these guidelines for in-sentence lists:
- Use a colon to introduce the list items only if a complete sentence precedes the list. In this problem version, the colon breaks right into the middle of a sentence (how dare it!):
Problem: For this project, you need: tape, scissors, and white-out.
Revision: For this project, you need tape, scissors, and white-out.
- Use both opening and closing parentheses on the list item numbers or letters: (a) item, (b) item, etc.
- Use either regular Arabic numbers or lowercase letters within the parentheses, but use them consistently. (Do not punctuate either with periods.) Use lowercase for the text of in-sentence lists items, except when regular capitalization rules require caps.
- Punctuate the in-sentence list items with commas if they are not complete sentences; with semi-colons if they are complete sentences.
- Use the same spacing for in-sentence lists as in regular non-list text.
- Make the in-sentence list occur at the end of the sentence. Never place an in-sentence list introduced by a colon anywhere but at the end of the sentence, as in this example:
Problem: The following items: tape, scissors, and white-out are needed for this project.
Revision: You need the following items for this project: tape, scissors, and white-out
Simple vertical lists
Use these guidelines for simple vertical lists:
- Introduce the list with a lead-in phrase or clause (the lead-in need not be a complete sentence; the list items can complete the grammar started by the lead-in). Punctuate the lead-in with a colon.
- Use simple vertical lists when the list items do not need to be emphasized and are listed vertically merely for ease of reading.
- Use sentence-style capitalization on list items.
- Begin run-over lines under the text of the list item, not the regular left margin. This format is called the hanging-indent style.
- Use the equivalent of a blank line above and below vertical lists.
- Either start list items flush left or indent them no more than half an inch.
- Use "compact" list format if you have just a few list items only a single line each. In the compact format, there is no vertical space between list items. Use a "loose" format—vertical space between list items—if the list items are multiple lines long.
- Punctuate list items only if they are complete sentences or clauses or phrases that complete the sentence begun by the lead-in (and use periods in these two cases).
- Watch out for lists with more than 6 or 8 list items; for long lists, look for ways to subdivide or consolidate.
- When possible, omit articles (a, an, the) from the beginning of non-sentence list items.
Bulleted Lists
Use these guidelines for bulleted lists (also referred to as unordered lists):
- Introduce the list with a lead-in phrase or clause (the lead-in need not be a complete sentence; the list items can complete the grammar started by the lead-in). Punctuate the lead-in with a colon.
- Use bulleted lists when the list items are in no necessary order but you want to emphasize the items in the list.
- Use asterisks or hyphens if you have no access to an actual bullet. Use your software's list styles for these vertical lists.
- Use sentence-style capitalization on list items.
- Begin run-over lines under the text of the list item, not the bullet. This format is called the hanging-indent style.
- Use 0.25 inches for the hanging indent (between the bullet and the text of the list item).
- Use the equivalent of a blank line above and below vertical lists.
- Either start list items flush left or indent them no more than half an inch.
- Use "compact" list format if you have just a few list items only a single line each. In the compact format, there is no vertical space between list items. Use a "loose" format—vertical space between list items—if the list items are multiple lines long.
- If you have sub-list items in a bulleted list, use a less prominent symbol for a bullet (such as a dash or clear disc), and indent the sublist items to the text of the higher-level list items. (It is certainly possible to have sub-numbered items within a bulleted list, in which case indent them the same as sub-bulleted items.)
- Punctuate bulleted list items only if they are complete sentences or verb phrases that complete the sentence begun by the lead-in (and use periods in these two cases).
- Watch out for bulleted lists with more than 6 or 8 list items; for long bulleted lists, look for ways to subdivide or consolidate.
- Avoid single-item lists. It's just like traditional outlines: if you have a 1 or an a, you need a 2 or a b.
- When possible, omit articles (a, an, the) from the beginning of list items.
ORed Lists
Computer developers like to use the Boolean OR as a verb. If two elements are logically joined by "or," they are said to be "ORed." An ORed list is simply a bulleted list with an "or" between the list items for emphasis. True, you can end the first item with with "or," but ORed advocates think that is not visually emphatic enough.
Numbered Lists
Use these guidelines for numbered lists (also referred to as ordered lists):
- Introduce the list with a lead-in phrase or clause (the lead-in need not be a complete sentence; the list items can complete the grammar started by the lead-in). Punctuate the lead-in with a colon.
- Use numbered lists when the list items are in a required order (for example, chronological) or must be referenced from somewhere else in the text.
- Type the number followed by a period; do not use parentheses on the number. Use your software's list styles for these vertical lists.
- Use sentence-style capitalization on list items.
- Use "compact" list format if you have just a few list items only a single line each. In the compact format, there is no vertical space between list items. Use a "loose" format—vertical space between list items—if the list items are multiple lines long.
- Begin run-over lines under the text of the list item, not the number. This format is called the hanging-indent style.
- Use 0.25 inches for the hanging indent (between the number and the text of the list item).
- Use the equivalent of a blank line above and below vertical lists.
- Either start list items flush left or indent them no more than half an inch.
- If you have sub-list items in a numbered list, use lowercase letters, and indent the sub-list items to the text of the higher-level list items. (It is certainly possible to have sub-bullet items within a numbered list, in which case indent them the same as sub-numbered items.)
- If you have sub-list items, use a less prominent symbol for a bullet (such as a dash or clear disc) or a lowercase letter for sub-numbered items, and indent the sub-list items to the text of the higher-level list items.
- Punctuate numbered list items only if they are complete sentences or verb phrases that complete the sentence begun by the lead-in (and use periods in these two cases).
- Watch out for numbered lists with more than 8 or 10 list items; for long numbered lists, look for ways to subdivide or consolidate.
- Avoid single-item lists. If you have a 1 or an a, you need a 2 or a b.
- When possible, omit articles (a, an, the) from the beginning of list items.
Two-column Lists
Use two-column lists when you have a series of paired items, for example, terms and definitions.
Two-column list Guidelines
- Introduce the list with a lead-in sentence that is a complete sentence. Punctuate the lead-in sentence with a colon.
- Column headings are optional; if used, align them to the left margin of the text of the columns.
- Either start list items flush left or indent them no more than half an inch.
- Use "compact" list format if you have just a few list items only a single line each. In the compact format, there is no vertical space between list items. Use a "loose" format—vertical space between list items—if the list items are multiple lines long.
- Use sentence-style capitalization for both columns.
- Punctuate items in the columns only if they are complete sentences.
- Left-align the items in both columns.
- When possible, omit articles (a, an, the) from the beginning of list items.
Note: The best way to create a two-column list is to use a table and hide the grid lines. If you use tabs between the columns, you are in for a mess if the text changes at all.
Lists with Run-in Headings
One last little variation on lists is the vertical list with run-in headings or labels at the beginning of the items. This format is used extensively in this book. It's like another way of doing a two-column list.
You can use bold or italics for the actual run-in heading (italics is used in the figure).
Nested Lists
A nested list contains two or more levels of list items. Nested lists can contain every combination of list type: numbered list items (123...) with lowercase-letter sublist items (abc...), filled-disc bulleted list items with clear-disc or hyphenated sublist items; and other combinations of these.
.
Figure 15.22. Example of a nested list. If the sublist items were in a required order, they would be abc....
Hanging Indents
Notice that all of the list-item "run-over" lines in this text and examples use a "hanging-indent" format. That's where any second and additional lines of a list item align to the text of the first list item. Not a good idea to use tabs or spaces to achieve this format.
In most versions of Microsoft Word, create this format by selecting hanging indent in Format > Paragraph and specifying an indent of 0.25 inches. Experiment with other indents.
Special notices are an important feature of professional technical writing: they highlight special information readers need to know to understand what they are reading, to accomplish what they want to do, to prevent damage to equipment, and to keep from hurting themselves or others. Look at these examples of Very special notices. State-of-the-art notices with clever comments.
Notices
- Use special notices to emphasize key points or warn or caution readers about damage or injury.
- Be careful to use the types of special notices precisely, for their defined purposes. Use the four types of special notices in the following ways:
Note—To emphasize points or reminders, or to indicate minor problems in a procedure.
Caution—To warn readers about possible damage to equipment or data, about potential problems in the outcome of what they are doing, or potential negative experiences (such as embarrassment).
Warning—To warn readers about the possibility of minor injury to themselves or others.
Danger—To warn readers about the possibility of serious or fatal injury to themselves or others.
Note: Take a look around your garage or kitchen, and look at the special notices you see on products. You will see plenty of variation, which is likely to be dependent on specific industry or corporate standards.
Guidelines for Notices
Deciding on which type of notice to use is not an exact science. Just don't use a danger notice when a warning is more appropriate (the same as "crying wolf"). Also, use notices in a consistent way throughout a document. Do not create your own notices, such as putting "Important:" in place of "Warning."
- Place special notices at the point in text where they are needed. For example, place a caution or danger notice just before or just after discussing a step in which readers might hurt themselves.
- Avoid having too many special notices at any one point in the text. Otherwise, the effectiveness of their special format will be lost. (If you have too many, combine them.)
- With warnings, cautions, and danger notices, explain the consequences of not paying attention to the notice. State what will happen if the reader does not heed the notice.
- The examples in this section use bold. Avoid all caps for the text of any special notice.
Note: In a properly set up publishing area, tech writers would not have to decide which type of notice to use or even craft notice language. That should be the job of organization attorneys. Still, those attorneys might be too busy to review your notices, and so the burden may still be on you the technical writer or editor.
Format for Notices
Use the following for specific details on the capitalization, typography (bold, underlining, different fonts, different types sizes), and spacing for each type of special notice.
Note
Format for a Note
- Type the label "Note" followed by a colon. (Although some of the following examples use bold, prefer italics to prevent visual confusion with headings.)
- Begin typing the text of the note one space after the colon. (But don't put the text of the note in bold or italics.)
- Single-space within the text of the note; skip one line above and below the note.
- Start run-over lines on the regular left margin.
- Align the note with the text to which it refers (as illustrated in the second example).
Figure 15.25. Example of a simple note
Figure 15.26. Example of a note within a bulleted list (not regular running text). This same principle (that special notices align to the text they refer to) applies to the other types of special notices as well.
Notes
Format for Multiple Notes
- Use this format when you have so many notes that they would be distracting to present individually.
- Type the label "Notes" followed by a colon. (Although some of the following examples use bold, prefer italics to prevent visual confusion with headings.)
- Use a numbered list for the individual notes; in it, follow the rules for numbered lists. (Do not use bold or italics for the individual notes.)
- Align the notes with the text to which they refer; skip the equivalent of one line above and below the notes.
Warnings
Warnings create a sense of urgency for the user and should be used only when serious injury or irreparable damage could result.
Format for Warnings
- Type the label "Warning," italicize it, and follow it with a colon.
- Either tab to beginning of the text of the warning, or use the hanging-indent format (which is much better). The hanging-indent format for the warning in the example below uses 0.63 inches for both the tab and the hanging indent, but font sizes will cause this value to vary.
- Use regular body font for the text of the warning notice (no bold, no italics, no all-caps, no color).
- Align the warning notice with the text it refers to.
- Skip the equivalent of one line above and below the warning notice.
Caution
Like warnings, cautions create a sense of urgency. However, cautions alert people to possible but minor injuries or reparable problems.
Format for Cautions
- Type the label "Caution" follow it with a colon, and bold both the label and the colon.
- Skip one line and begin the text of the caution aligned with the start of the caution label.
- Single-space the text of the caution; skip one line above and below the notice.
- Align the caution notice with the text it refers to (in the preceding, the warning notice occurs within a numbered list and is indented accordingly).
Figure 15.29. Example of a caution notice. Use this one to alert readers of possible damage to equipment or problems with the procedure.
Danger
Danger notices should be used only to warn the user of life-threatening results.
Format for Danger notices
- Type the label "DANGER" in all-caps bold.
- Align the danger notice with the text it refers to.
- Single-space the text of the danger notice; skip one line above and below the danger notice.
- Use bold on the text of the danger notice if you have it (but never all-caps).
- If you have graphics capability, draw a box around the danger notice (including the label).
Other Formatting Issues
Here are some additional points to consider concerning special notices:
Special alignment: Special notices must align to the text to which they refer. For example, if you have a note that adds some special detail to something in a bulleted list item, you must align that note to the text of the bulleted item. Of course, if the note follows a bulleted list but refers to the whole list, then you can use the regular left margin.
Single-spaced text: All of the examples and discussion in this unit are based on single spaced text. Leave either one blank line between running text and special notices—depending on what looks best to you. (And of course both running text and the text of the special notices would be single spaced.)
Placement of Special Notices: Place special notices just before or just after the point at which they are relevant. For example, you can warn readers to back up all data before you tell them to reformat their hard drive. However, in practice serious special notices are placed at the very beginning of a procedure where great harm to data, equipment, or people is likely to occur.
One technique used by very cautious writers (maybe those who have been burned) is to place all serious notices (warnings, cautions, and dangers) somewhere at the beginning of the document, and then repeat them individually where they apply. An organization is likely to have a style guide that states requirements on placement of notices.
Multiple Special Notices: You run into situations where you have three or four special notices, all jammed together in the same part of the text, each one following another. This is a problem because the whole point of the special formatting of the notices is lost: something is special because it is different from the surrounding. The solution to this problem is to create one identifying heading (for example, "Notes and Warnings"), and then list the notices (either bulleted or numbered) below it.
Highlighting as the term is used here, is the use of typographical effects to call attention to text. These effects can include italics, bold, all-caps, quotation marks, color, and so on. Highlighting calls readers' attention—or "cues" them"—to actions they must take or to information they must consider carefully.
One of the problems in technical writing—in particular, technical writing about computers—involves the use of the various techniques for emphasis. Unfortunately, some technical texts go overboard on the use of the various emphasis techniques which are discussed here.
Highlighting Fundamentals
Consider a few fundamental principles of emphasis:
- Practically any special textual effect that is different from regular body text can function as an emphasis technique. Things like italics, bold, underscores, caps, different size type, alternate fonts, color, the various graphical ingenuities (showing, reverse color, outline fonts) can act as emphasis techniques.
- Used in excess, any emphasis technique or combination of emphasis techniques can lose their ability to emphasize and become busy and distracting. Used in excess, any emphasis technique or combination of emphasis techniques can cause readers to be reluctant to read a text, if not avoid it altogether. Notice how unreadable the overly highlighted version of the notice is in this popup
- When extended text must be emphasized, use the special notice format (rather than creating all-bold or all-caps paragraphs, for example).
- A carefully planned functional relationship must exist between the text that is emphasized and the emphasis technique that is used.
- Emphasis techniques must be used consistently to prevent readers from becoming confused.
- To promote consistency, you must use a style guide or style sheet, which records and then dictates all of your decisions about how you are going to use emphasis techniques.
- To help your readers understand your highlighting scheme, you can include a brief section somewhere in your document (usually in the preface) explaining how you're going to be using the emphasis techniques.
In the following discussion, you'll notice that any system of emphasis techniques can get quite complicated and hard to remember for writers and editors. You'll notice that there are many equally valid ways of using emphasis techniques: for example, in some cases, it's arbitrary whether you use bold or italics for simple emphasis. To address this problem, you must document your highlighting guidelines in a style guide that writers and editors (or just you) can refer to. A style guide is simply a record of the decisions you and your documentation team have made about how you want your documents to look.
Your readers also need to be informed as to the highlighting scheme you plan to use. This can be handled in the preface: include a section called "Highlighting" or "Typographical Conventions" where you list how you use italics, bold, fonts, and other such effects.
Specific Emphasis Techniques
This next section goes one by one through the various emphasis techniques, explaining the common practices. To keep things simple, highlighting issues for tables, figures, headings, lists, and notices are presented in those sections.
Bold
In publishing, technical publishing in particular, usage is mixed as to whether to use bold or italics for basic emphasis. For example, if you want to emphasize that readers should not turn off the computer without first shutting it down, the "not" can be bold or italics. Traditionally, italics has been used, but, perhaps because of computers, bold is commonly used as well.
Whichever technique you use, use it consistently throughout your text or library of related texts. By the way, readers are not likely to be able to distinguish between levels of emphasis: for example, using italics for important text and bold for very important text is likely to be lost on most readers.
If you are tempted to make an entire paragraph bold, remember one of the principle of emphasis discussed above: using too much of an emphasis technique causes the effect of the technique to be lost. Not only that, but too much emphasis makes readers less inclined to read. Instead of carefully reading an all-bold paragraph, readers may just ignore it entirely!
Instead of creating an all-bold paragraph, use the special-notice format. In it, a key word (for example, Important, Note, Danger, Caution, Warning) is bolded, while the rest of the text is left regular roman (that is, the same font and style as the regular body text).
Legitimate use of bold in technical texts varies widely. As long as you develop a scheme that is directly related to the reader's need and to the characteristics of the text (or technology) and that does not lead to overkill, your use of bold should work fine.
Here are some common, standard uses of bold:
- Simple emphasis. As discussed in the preceding, some technical texts use bold for simple emphasis instead of the traditional italics. For example, "Do not turn off the computer before shutting it down."
- Commands. Computer texts commonly use bold for commands, for example, "Use the move command to rename UNIX files." See the section on highlighting computer text for a review of the complete set of emphasis techniques.
- Buttons that initiate commands. In a graphical user interface, some of the buttons initiate commands. For example, "press the Exit button to exit the application."
- Field labels. While some computer text bolds field labels, it is not general practice because it leads to highlighting overkill. For example, "In the Indentation area of the dialog box, click on Left." More common is to use the cap style used on the screen. It's preferable to write this: "In the Indentation area of the dialog box, click on Left."
- Icons or keyboard or mouse buttons. While not universally observed, another highlighting technique that follows this system logically is to bold the name of a keyboard key or mouse button. For example, "Press the Q key or the left mouse button." In keeping with this system too is to use bold on icons: "Click the Start icon."
- Labels on hardware. Another practice that is common in computer publishing is to bold the name of a hardware label. For example, "Press the Reset button to reboot the computer."
You'll notice that the preceding discussion stated no absolute rules. That's the way it is—technical publishing practice is quite varied. The main idea is to develop a logical, controlled system of highlighting, use it consistently, and document it in a style guide so that you and your documentation team members can refer to it.
Italics
Here are some of the standard uses for italics:
- Simple emphasis. As mentioned earlier, usage is mixed on whether to use bold or italics for simple emphasis, although italics has been traditional: for example, "Do not turn off the computer before shutting it down." Whichever you use, be consistent with it, and document it in your style guide or style sheet so that everybody on your document team can see it. If you're not sure which to use, use italics for simple emphasis: it's less busy.
- Variables . In computer publishing, one of the most common uses of italics is for variables. For example:
copy oldfile newfile
Users know not to type oldfile or newfile but to substitute their own file names instead.
- Definitions in definition (two-column) lists. While bold is more common for the items in the left column of a two-column list, italics is also used. (See the discussion of two-column lists in the preceding section on bold.)
- Terms where the term is defined. A nice touch is to italicize a word where it is defined in regular body text.
Underscores
There is almost no reason for using underscores in technical text. In the days of typewritten text, there certainly was. However, in these times, when bold, italics and other such typographical effects are readily available, underscores look obsolete. If you want to emphasize something, use your standard guidelines—for example, use italics or bold. Don't try to create gradations of emphasis: for example, a scale of increasing importance ranging from italics to bold to underscore will be lost on your readers.
If you see good use of underscores in technical text, it will probably occur in heading design.
Capitalization
In technical publishing, there seems to be a running battle between technical writers and technical experts over capitalization. Technical experts like to use initial caps for practically every component and process in a system. Also, technical experts (and management) typically use all caps for the text they consider important and want readers to attend to. Meanwhile, technical writers and editors (rightly) insist on using caps for proper names only.
As a technical writer, hold the line against capitalization. Capital letters are distracting; all-caps text is uncomfortable to read. Capital letters create a busy text, which sends lots of unnecessary signals. Capital letters are traditionally intended for proper names such as Microsoft, Netscape, Gateway, Dell Computers, WordPerfect, and so on. The classic guideline in technical publishing is to capitalize the names of separately orderable products only. However, the politics of organizations bend this guideline considerably. If a company is proud of a certain feature in its new release, for example, EnergyMiser, it will capitalize it, even though you can't order it separately.
Guidelines for Capitalization
- Use the exact capitalization style of messages shown on the computer screen, menu or screen names, field names, hardware labels, and so on. (In rather old interfaces, all-caps was used for things like field, menu, and screen names. A common practice in these cases is to use initial-caps for references to these things in the regular text. The principle here is that unnecessary all-caps in regular text is distracting.)
- Do not use capital letters for emphasis; use italics or bold instead.
- Do not use all-caps for any extended text; use the special-notice format instead.
- Do not capitalize the names of the components or processes of a product. Capitalize only the names of products, that is, components that are separately orderable.
For example, your product may be called WordStuff and of course it must be capitalized according to the style dictated by the marketing and product planners. However, one of WordStuff's features called "spell checker" shouldn't be capitalized—just about everybody has one of those. However, WordStuff may have a feature called "ZippyFormat" and another called "Image Worker." Even though these are not separately orderable, you will want to use the initial-cap style because of their special style and their marketing value. "Image Worker" is obviously something WordStuff, Inc., wants to show off—therefore, the caps.
But when you have to break rules like this, the exceptions need to go in the style guide or style sheet.
Single or double quotation marks
Quotation marks are often mistakenly used as emphasis techniques in technical text. As a technical writer, limit quotation marks to the traditional usage, which includes quoted speech; numbers, letters, or words referred to as such. Quotation marks, like capital letters, tend to create a busy, distracting text and therefore should be avoided.
One legitimate use of double quotation marks is odd, quirky, nonstandard use of words. For example:
In a core dump, the computer "barfs" all data into a single file.
Well-designed computer text avoids quotation marks rather vigorously. One of the primary reasons is that some readers might mistakenly assume that they must include the quotation marks in the commands they enter.
Problem: Use the "move" command.
Revision: Use the move command.
Problem: Enter "copy install installnow."
Revision: Enter copy install installnow.
Note: While some technical texts have well-defined uses for single quotation marks, in general there is no standard use for single quotation marks, other than the traditional quotation-within-a-quotation rule and the quirky-usage rule. When you see single quotation marks within technical text, there is usually no more rationale for their use than there is for double quotation marks.
Alternate fonts
One of the most common styles involving alternate fonts is to use Courier or some similar monospaced, old-typewriter-style font in contrast to the standard body font (such as Times New Roman or Helvetica). You can create this effect in web page by using a CSS style like <span class="example_text">. For example, "type install to install the program."
Here's a review of the common uses of alternate fonts:
- Example text. To signal that an example rather than a required entry is being shown, an alternate font like Courier is often used:
For example, if you want to copy a file, type copy yourfile.txt myfile.txt. A file called myfile.txt will be created, and its contents will be the same as yourfile.txt. - Displayed text. Computers and other equipment typically display things such as warnings or status codes or error messages. These appear on monitor or in LCD panels and the like. When you refer to this displayed text, you can use an aternate font such as Courier. For example, "If the directory does not exist, the system will respond with No such file or directory." Or, "As the computer boots up, the digital read-out window will display 8888."
- Extended code samples. In computer programming texts, extended programming samples are often shown in Courier, for example:
#check for mean hackers
if ($address1 eq "" & $address2 eq "") { &wicked_address (500, "Search Error", "Please enter a name."); } elsif ($address1 =~ /[;<>&\*`\|]/ | $address2 =~ /[;<>&\*`\|]/) { &wicked_address (500, "Search Error", "Malformed e-mail address. Please do not destroy our poor, humble, one-virtual-room schoolhouse!."); }
Color
Color is used in technical text but it is expensive and hard to manage through the publishing cycle.
However, color is easy to use in online information. It's common to see hypertext links, for example, using color. Online helps typically use green while web pages typically use blue for new links and purple for links the user has already explored.
The tendency to use color indiscriminately in online information is much like the tendency to go wild with bold, italics, type sizes, and alternate fonts in hardcopy information. The feeling must be something like, "It's there, it's cool, so let's use it!"
There are not any strongly developed trends in the use of color in technical text, either online or hardcopy, other than the use of green and blue for hypertext links, mentioned earlier. Printed technical texts rarely use color because of the cost. Of course, if the documentation ships as a PDF, then color can easily be used, and it's up to the reader whether print it out with a color printer.
If you want to use color, plan it carefully. Don't expect readers to remember that red signals one idea, blue another idea, and green still some other idea. Just stick to one color. In general, avoid using color for extended text. Instead of making an entire warning notice red, just make the Warning label red and leave the warning text regular roman (text like the regular body text).
Better still, read some of the standard literature on color in the technical communication field. There are general design issues and international issues.
Combinations of the preceding
In general, it's a bad idea to combine emphasis techniques, for example, bold and italics. In non-professional technical text, you'll see such garish combinations as all all-caps bold-italics or all-caps bold-italics with double quotation marks. Avoid these!
One legitimate combination is to use italics with alternate fonts. For example, when you show the syntax of a command, you want the entire text to be in Courier, but you also want the variables to be in italics: copy OldFileName NewFileName
Functional names for character styles and tags
If you have ever been around the publishing industry, you may have encountered something called semantic markup. This means naming sections of text according to the structural role they play in the document—for example, heading. The reader does not see these names, but they play an important role in how the document is formatted and how it can be reused.
This same idea applies to words in phrases within text. For example, in the HTML for a web page, you can use the <b>bolded word</b> tags to make a word bold. But bold does not indicate the function of the word or phrase. Instead, command or interface_label would. Therefore in semantic markup using HTML CSS, things are more functional if they look like this: <span class="command">bolded word</span>.
Files using HTML and CSS are typically converted to other media such as PDF or even to and from XML. Using functionally named highlighting styles, as described just above, can greatly ease the conversion process.
Further Explorations
Once you've read the preceding, a good thing to do next is to explore technical publications to see what highlighting schemes they use. Watch for the way things like bold, italics, caps, alternate fonts, and other such effects are used. Most likely, you'll see very different usage than what you've read about here. As you explore, think about the logic of the emphasis techniques you see being used; try to formulate the rules that the writers seem to be using; watch for inconsistencies in highlighting; and think critically about the usage you see—is it logical? overkill? "underkill?"
Highlighting Scheme
If all the options and alternatives discussed previously have you overwhelmed, consider using the following highlighting scheme. It's based on highlighting you'll find in many UNIX, Windows,and Linux documents.
| Names of fields, tabs, folders, dialogs (boxes), menus | Cap style on screen; regular roman |
| Names of icons | Cap style on screen; bold |
| Buttons (or functional equivalent if not so labeled) | Cap style on screen; bold |
| Menu selections, selectable options | Cap style on screen; bold |
| Commands entered verbatim with no parameters or flags | Bold |
| Text entered or displayed | Courier New; 1-point size smaller than body font |
| Variables | Italics; regular roman |
| Programming code | Courier New; 1-point size smaller than body font; regular roman |
| Labels on hardware | Courier New; 1-point size smaller than body font; bold |
Notes:
- Regular roman refers to whatever the font and font size that is used for body text.
- While these suggestions recommend "cap style on screen," developers sometimes have an unfortunate tendency to use all caps. Because an all-caps style cuts down on readability, use initial caps (title case).
- If you show users how to enter a command including example text, don't bold the command that occurs in the example text:
Use the mv comand to change the name of location of a file, for example:
mv thisfile.txt thatfile.txt. - If you show users how to enter a command including example text, and include variables in the example text, use italics on on the variables.
Use the mv comand to change the name of location of a file:
mv my_file.txt your_file.txt. - If you simply refer to the name of a screen or menu that is not clicked or initiates any event, use cap style on screen and regular roman.
- Some styles bold the action that users are to take (for example, press, enter, delete). That certainly is an option, but for me it's too much highlighting.
Index
As a technical writer, you'll typically have to create indexes for the print books and for online helps you develop. The type of index we mean here is the classic back-of-book index that shows page numbers on which topics and subtopics occur within the book. An online index is much the same except that you supply hypertext links rather than page numbers.
Rough-drafting an Index
As with any writing project, there is a rough-drafting phase for indexing. And of course, you need to think about your audience—who they are, how they'll use the index, why they'll use it, and what sorts of terminology they might be accustomed to. After that, here's what to do next:
- Convert each heading into multiple index entries. Headings are a good place to start: they indicate topics and subtopics—precisely what an index does. However, don't just copy headings directly into an index and walk away. As you will see below, you need to cross-list heading-based entries in as many ways as practically possible.
- Cross-list each entry. Rearrange each of your heading-based entries in as many practical ways as you can. For example, a heading such as "Changing screen resolution" can be indexed as "screen resolution, changing" as well as "changing screen resolution." You might also include "resolution, changing screen." These cross-listed entries attempt to anticipate all the likely ways a reader might look for this topic in an index: "screen," "resolution," or "changing."
| Heading | Index entries |
| Optimizing Video Display | video display, optimizing optimizing video display display, optimizing video |
| Playing Streaming Multimedia | streaming multimedia, playing playing streaming multimedia multimedia, playing streaming |
| Networking Basics | networking networks |
| Introducing Streaming Multimedia | streaming multimedia multimedia, streaming |
Note: You can't always cross-list index entries on every word. For example, "introducing streaming multimedia" in the preceding just wouldn't work. Would any reader ever look for this topic starting with "introducing"?
- Create synonym entries. Readers don't necessarily use the same terminology as you do in your documentation. They may call a diskette drive a "floppy drive." They may refer to a display as a "monitor." As an indexer, you must anticipate these common variations in terminology. In the preceding entries, it would be a good idea to have a synonym for "video display" such as "monitor." But instead of repeating the page numbers, use a See reference. That way, you point readers to the preferred term. (Of course, if there is only one page number, just repeat it with the synonym entry.)
| Index entry | Synonym entries |
| volume, adjusting | loudness, adjusting |
| transmission rate | speed, transmission |
| capturing video | copying video |
- Review the text for additional index entries. It's ordinarily not enough just to index by headings. You have to dig down in the text for concepts, terms, and tasks that are not represented by the headings. For example, under the heading "Creating a Multimedia Stream," you might see definitions of "capturing" and "encoding." These are important terms, but they appear nowhere in the headings—index them too! In this case, you'd want to create these additional index entries: "capturing streams" and "encoding streams."
- Index front and back matter. Don't forget to dig around in the preface, safety notices, appendixes, and other such peripherals for additional index entries. Typically, technical-support numbers and addresses are shown in the preface. Index them—and don't forget to create cross-listed entries and synonym entries for them as well.
| Index entry | Cloned and synonym entries |
| technical support | support, technical help desk problems |
Revising and fine-tuning an index
Once you've brainstormed all the index entries that you can think of, it's time to see what the index looks like and start working it over. To revise a rough-draft index:
- Build a first-draft index. Once you've created as many index entries, cross-listings, and synonyms as you can, it's time to "build" a first draft of the index. Unless you are working the old-fashioned way with index cards, you can get your software application to do this for you. For example, if you work in a desktop publishing system, you've gone through your text inserting index entries. The same process applies to help-authoring tools. When you build the first-draft index, don't be dismayed. It's just a rough draft, to which you'll need to apply several kinds of revision.
- Toss useless entries. In the preceding steps, you've been rough-drafting the index. In that phase, you don't get hung up about the exact phrasing of entries or the likelihood that anybody would ever use them. But now is the time to start weeding out the entries that no reader would ever use. For example, first-level entries beginning with "introducing," "using, "about" are not likely to be useful. Delete them! But don't delete them from the built index. Go back into your document and get rid of the original index entry.
- Consolidate entries with similar phrasing. You'll also find lots of entries that have only minor variations in phrasing. For example:
Rough-draft entries Revised entries technology, streaming multimedia
technologies, streaming multimediatechnologies, streaming multimedia video display
video displaysvideo displays change screen resolution
changing screen resolutionchanging screen resolution
As you can see in these examples, singular/plural entries and verb variations are the most common causes of similar phrasing in index entries. Your house style may dictate using singulars as opposed to plurals. Whichever way you handle these, just be consistent.
- Group similar entries. You'll also see entries that need to be grouped and subordinated. For example, they may all begin with the same word, but have different modifiers. Here's an example:
Similar entries Grouped and subordinated entries projector, defined
projectors, compiling
projectors, considerations
projectors, creating
projectors, troubleshooting
projectors compiling
considerations
creating
defined
troubleshooting
- Rework entries with excessive page entries. Some organizations have actual style-guide rules concerning how many page references following an index entry are allowable. Three is a common maximum; two is aggressive, ambitious. For example, "programming syntax, 12, 45, 74, 122, 219, 222." A string of anonymous page references like this helps no one. Instead, identify the subtopic for these page references. Here's a example:
Too many unidentified page references Subordinated and labeled entries projectors, 124, 136, 154-155, 156 157 projectors compiling, 154-155
considerations, 156
controls, 136
defined, 124, 136, 157
A very good touch you don't often see in indexes is the page range on which a topic is discussed—even if there are subentries. If it were accurate, you could have entry like this: "projectors, 126–137"
- Look for entry groupings. A nice useful touch in indexes is to hunt for ways that you can group entries. For example, imagine a user guide that explains the various dialog boxes that pop up in the application. There's the Password dialog box, the New User dialog box, the Delete User dialog box, and so on. How about repeating all those entries under "dialog boxes"?
Entries Grouped entries (entries are scattered throughout the index) Add User dialog box
...
Delete User dialog box
...
New User dialog box
...
Password dialog boxAdd User dialog box
...
Delete User dialog box
...
dialog boxesAdd User
Delete User
New User
Password
...
New User dialog box
...
Password dialog box
- Look for shift-up entries. In your indexing work, you may have some subentries that need to be copied out as main entries.
Entries Shifted-up entries
(entries are scattered throughout the index)batteries disposing, 33
explosion warning, 34
manufacturer recommendation, 34
polarity, 33-34
purchasing, 33
replacing, 33-34
tabs, 33(illus)
batteries disposing, 33
explosion warning, 34
manufacturer recommendation, 34
polarity, 33-34
purchasing, 33
replacing, 33-34
tabs, 33(illus)
disposing, batteries, 33
...
polarity, batteries, 33-34
...
warning, battteries, 34
...
In this example, the indexer thought some (probably not many) readers would look up "polarity" first as opposed to "batteries, polarity." Similarly, the indexer thought people might look up "disposing" first. Even though possibilities like these are small, put them in the index anyway.
- Look for See also and additional See references. Toward the end of your revising phase, take a look at your index for the possibility of See also references. See also references are for closely related terms that readers might choose by mistake. For example, in the old DOS systems, there was the copy command and the xcopy command. The two commands are so closely related in name and in function that you'd want to put See also references to each other. And don't forget the See references: those point readers from synonym terms to the terms you prefer to use and index by in your book.
- Check the style and mechanics of index entries. The organization for which you work may have its own house style guide or refer you to some standard style such as the Chicago Manual of Style. Look at these very carefully for how they tell you to capitalize and punctuate index entries. Indexes commonly use lowercase on all nonproper-noun entries, but a certain percentage do use initial caps on first-level entries. Most styles have you put a comma just after the index term and before the page numbers; but a few do not. Some styles require you to use the same highlighting in the index as you do in the main text. If something is bold in the main text, they want it bold in the index too.
Note: This chapter uses a variety of punctuation and capitalization styles—not to confuse you, but to make you aware of stylistic variability.
One common index style Another common index style projectors, 123 compiling, 154-155
considerations, 156
controls, 136
defined, 124, 136, 157
project profiles, 451-461
projectors compiling 154-155
considerations 156
controls 136
defined 124, 136, 157
Project profiles 451-461
Notice in the right-hand example that there is no comma between the index term and the page references. Also, you'll find that some indexing standards and styles disapprove of having a page reference on an index entry that has subentries: for example, "projectors, 123" in the left-hand example. Why isn't the page 123 reference down amongst the sub-entries? Just what is the subtopic on page 123?
References
Gatlin, P. L. (1988). Visuals and prose in manuals: The effective combination. In Proceedings of the 35th International Technical Communication Conference (pp. RET 113-115). Arlington, VA: Society for Technical Communication.
Große, C. S., Jungmann, L., & Dorchester, R. (2015). Benefits of illustrations and videos for technical documentation. Computers In Human Behavior, 45109-120. doi:10.1016/j.chb.2014.11.095
Levie, W.H., and Lentz, R. (1982). Effects of text illustrations: A review of research. Journal of Educational Psychology, 73, 195-232.
This work "Visuals in Technical Documents" is a derivative of Business Writing Chapter "Visuals in Business Documents" by Heather Katzoff, Open Technical Communication, Chapter 4.7: "Tables, Chart and Graphs” and 4.8 "Graphics" by David McMurrey and Tamara Powell, Online Technical Writing Chapter "Document Design" by David McMurrey, and Technical Writing for Technicians CC-BY Will Fleming used under a CC BY license. "Visuals in Technical Documents" is licensed under CC BY 4.0 by Mary Richards.