Working with illustrations
This chapter discusses the issues involved with illustrations, which
can be line art or imported graphics or pictures, including:
These are discussed in the following sections.
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
- Make decisions about sizes and formats when other documents are
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
- 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).
There are many kinds of illustrations used in our technical
- 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
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.
Format illustrations in a consistent fashion throughout a given
document and across all documents.
Apply the following type standards for all illustrations:
- Use a 10-point serif font for all body text.
- Headings, if needed, are in boldface.
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.
In general, the following style rules apply to all illustrations:
- Illustrations should never extend beyond the left or right
- Illustrations should never extend beyond upper or lower text
- 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
- 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
- Use a 1-point pen for lines and arrows.
- Lines (without arrowheads) should be used to show static
- Arrows (with arrowheads) should be used to show direction or
- 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
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
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
- 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.
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,
- Lines should break around text rather than cross the
- 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
- Reserve arrows for showing direction or motion; for example,
a knob to turn or a door to move.
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
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.
Jump to table of contents
Back to Chapter 11, "Working with flowcharts"
Onward to Appenddix A, "Style reference"
Copyright © 2001 Joshua S. Simon.