Last update Dec29/19W3C//Dtd html 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> Master Style Guide: Chapter 12

Chapter 12
Working with illustrations

This chapter discusses the issues involved with illustrations, which can be line art or imported graphics or pictures, including:

Creating illustrations
Illustration types
Standardizing styles

These are discussed in the following sections.

Creating illustrations

There are several techniques for creating illustrations. Some technical writers write the text first and then think of ways to illustrate it. Others devise a concept for an illustration and write the text around it.

At an early stage of the document it is essential to both the technical writer and the technical illustrator, if different, to discuss the possibilities. The goal is to let the illustrator

Get an overall indication of the document's direction.
Integrate existing illustrations into the new document, to maintain continuity.
Make decisions about sizes and formats when other documents are being developed.

When developing illustrations, consider the following:

What is the illustration supposed to show or indicate, including, but not limited to, perspective views, amount of detail, and figure type? For example, it could be a front or back or cutaway view of some hardware, or a process flow for software, or a representation of a command line or screen shot.
Calculate the size of the figure. Eliminate unnecessary use of whitespace.
Review existing illustrations for figures that can be reused or copied and used as a base for the new illustration.

Illustrations can be created in any graphics-capable tool, including publishing tools (such as Microsoft Word or FrameMaker) and graphics tools (such as Visio).

Illustration types

There are many kinds of illustrations used in our technical documentation, including:

Block diagrams and functional flow diagrams (flowcharts)--These illustrations show the relationship between functional units or processes. More information can be found in Chapter 11, "Working with flowcharts."
Line drawings--These are drawn in two or three dimensions and emphasize the relative position or placement of the object or concept portrayed. This can include clip art from the publishing tool's library or other sources.
Screen images--A representation of terminal or computer screen output, used to show users what they see before or after certain operations.

Deciding how illustrations can best be used requires judgment. It is often helpful to consult with an illustrator, other technical writers, and end users of the proposed document during the documentation process.

Standardizing styles

Format illustrations in a consistent fashion throughout a given document and across all documents.

Standardizing typefaces

Apply the following type standards for all illustrations:

Use a 10-point serif font for all body text.
Headings, if needed, are in boldface.

Standardizing formats

This section discusses the standard formats for all illustrations as well as the specific standard changes for illustrations that are used within documents as opposed to those that are entire documents.

All illustrations

In general, the following style rules apply to all illustrations:

Illustrations should never extend beyond the left or right margins.
Illustrations should never extend beyond upper or lower text boundaries.
If you must break illustrations between pages, code flow lines to march across pages.
Leave a 1-line space before and after an illustration.
Use a 2-point pen for components except connecting lines.
Every component (other than lines) should have a shadow beneath it. The shadow may be a consistent gray or be color-coded at the discretion of the author. The shadow should appear below and to the right of the component, offset about 6 to 12 pixels from the component.
Use a 1-point pen for lines and arrows.
Lines (without arrowheads) should be used to show static connections.
Arrows (with arrowheads) should be used to show direction or movement.
Arrowheads should be filled solid, using a solid triangle as the pointer. Arrowheads should never be hollow (using a hollow triangle as the pointer) or just lines (using two lines as the pointer).

Illustrations within a document

Some style guidelines vary depending on whether the illustration is contained within a technical document or comprises the entirety of a technical document.

If the illustration is contained within a technical document:

The illustration should be treated as a figure.
The illustration should have a descriptive caption (such as "Figure 123 Hardware diagram").
The illustration may be left-aligned with the text above and below it or may be centered within the figure.
The illustration should fit in the same space as the body text. The left margin should be 1 inch greater than the right margin.
The illustration should be contained in a border, such as a 2-point rounded rectangle. This border indicates to the reader exactly what is contained within the figure.

Illustrations that are the document

If the entire document is an illustration:

The illustration should not have a caption.
The illustration may be left-aligned on the page or may be centered on the page at the discretion of the author.
The illustration should fit in the same space as the body text. The left margin should be 1 inch greater than the right margin.

Standardizing callouts

A callout is a boxed sentence or fragment of text used to highlight a particular area within an illustration. The following callout standards apply to all illustrations:

The main component or system in the illustration should be labeled as it is in the text.
Illustrations should not include instructions.
Label all parts that are mentioned in either the illustration title or within the text introducing the illustration.
Use down style capitalization for labels and titles.
Use all caps for acronyms and view labels (such as FRONT, REAR, and SIDE).
Lines should break around text rather than cross the text.
Command names should follow typographic conventions as if they were in text.
Keep callouts as brief as possible. The nomenclature must exactly match the nomenclature used in other parts of the document.
Reserve arrows for showing direction or motion; for example, a knob to turn or a door to move.

Standardizing punctuation

Punctuation, symbol, and abbreviation standards apply to text used in illustrations as well as paragraph body text. The sole exception is when noting nomenclature as recorded on hardware. Hardware nomenclature must match what is on the hardware.

Ensure that the wording in an illustration is correct and accurate, and that the wording, nomenclatures, and abbreviations obtained are correct.

Using footnotes with figures

If footnotes are necessary with an illustration, place the footnote one line under the illustration endline. Type the footnote superscript number in italics. The footnote itself is in regular body text but one point size smaller (for example, if the body text is in 11-point Times Roman the footnote text is in 10-point Times Roman). Footnotes longer than one line start at the left margin and end on the right margin. Footnote copy should be single spaced, with a single space between each footnote. Sources for illustrations copied (with permission) from elsewhere are identified immediately after the illustration and are not introduced by a superscripted number.

Using turnpage figures

If an illustration is too wide to fit between the right and left margins and it is impractical to divide the illustration into two parts, rotate the illustration 90 degrees counterclockwise (turnpage) rather than use a foldout page.

All turnpage illustrations are full page. The header and footer remain on the top and bottom of the page (normal portrait view) even if a turnpage (landscape view) figure is used.