T. R. Girill
Society for Technical Communication/Lawrence Livermore National Lab.
Technical Writing: Lessons from Explanatory Graphics
In January, 2013, Niloy J. Mitra and colleagues republished
a clever article from 2010 on how they developed algorithms to
(almost) automatically generate explanatory diagrams
("how-things-work visualizations") for mechanical assemblies
(N. Mitra, et al., "Illustrating how mechanical assemblies work,"
Communications of the Association for Computing Machinery,
Jan. 2013, 56(1), 106-114, DOI 10.1145/2398356.2398379).
Relevant to those of us concerned with building literacy is not
their computer science moves here, however, but their explanatory
ones: they isolated three features that successful explanatory
diagrams need, they suggested a textual counterpart for each,
and they built into their CAD/graphics software responses to the
prime USABILITY challenge that each such feature faces.
One key feature of any diagram that adequately explains a
mechanical assembly is motion arrows, visible vectors that
"indicate how individual parts move" (106) relative to other
important parts. Such directional arrows fill the same explanatory
role as do verbs (slide, turn, place) and adverbs (vertically,
slowly, clockwise) in instruction or description text. Verbs, like
arrows, reveal action and interaction.
One big usability challenge for verbs (in text) or motion
arrows (in diagrams) is user viewpoint. Whether a part is placed
vertically or horizontally, or turns clockwise or counterclockwise,
often depends on the vantage point of the viewer (who for repair
tasks may also be the actor or "drive part"). So audience
assessment becomes a crucial aspect of explanatory success in
both the text and graphics cases. The how-things-work software
project included code to place arrows where they were (1) easy
to detect and (2) not hidden by other parts, for the intended
Managing relevant detail is a second shared goal for explanatory
text and diagrams. Hence, a second key feature is a "frame
sequence," one "that highlights the propagation of motions and
interactions from the driver [part] to the rest of the
assembly" (111-112). A frame sequence in a diagram thus fills the
same role as do comparisons and contrasts in a textual explanation.
Well chosen text comparisons reveal and clarify steps in a causal
chain or functions of a tool or device, a kind of verbal
One major usability challenge for textual comparisons and
graphical frame sequences alike is managing (verbal or visual)
clutter (to actually focus reader attention and achieve the
sought highlighting). The how-to-diagram software responded to
this challenge by COORDINATING frames and arrows, so that "every
highlighted part [the intended focus of each frame] has at least
one arrow" (112). This is quite like using consistent, coordinated
comparisons (and even just consistent units or benchmarks) across
multiple items in a verbal explanation. In both cases the explainer
must plan ahead, but the user benefits from a much clearer account.
Signaling important relationships is a third explanatory goal
that text and diagrams share. A good assembly diagram reveals
(causal) behavior, not just current positions (even if the motion
is only in the viewer's imagination rather than a video sequence).
Among the visual signals that fill this same relationship-
disclosing role in explanatory text are
* lists (whose displayed items are thus signalled to
all be members of the same class--of things, actions, claims, etc.),
* tables (whose row and column structure and labels
relate the tabulated entries to each others), and
* hierarchical headings (which signal the subordination
of topics to one another).
One usability challenge for text or graphics that strives to
reveal relationships is managing time relations just as effectively
as space relations. This often calls for translating the former
(can be abstract) into the latter (where people are more
psychologically adept for evolutionary reasons). The software
of the how-things-work project, for example, used stop motion
(freezing key frames at crucial times) and exploded views (to
make simultaneous actions more clear in space) as a response.
Of course the more parts that are involved the more visual
compensations are needed, just as with complex text where
more elaborate textual organizers are needed.
This look at one ambitious explanatory graphics project is
relevant to anyone teaching effective technical communication for
two reasons. First, it shows the importance of text-graphics
integration (a major Common Core literacy theme). And second,
is shows how much usability principles, derived from empirical
human factors research, apply with equal importance whenever
reliable explanation is the goal. Students can apply that insight
both when they write and when they draw.