Three minutes into my talk at my first meeting of the IFIP working group on programming methodology (WG2.3), Edsger Dijkstra raised his hand -- or not -- and said: "Why is this arrow red and that one blue?" The meeting's chair (Natarajan Shankar) saved me by saying, "You don't have to answer that" and urging me to go on. Dijkstra was notoriously hostile to fancy presentation tricks and any kind of bling-bling. I am not sure he ever reconciled himself with PowerPoint. But he had a point. Too often, technical texts use pictures as a substitute for substance.
Graphical illustrations can be a great help for understanding. They are particularly appropriate to give a general idea of the structure of problems and solutions. Their use, however, requires caution. (These observations are for the most part excerpted from my forthcoming book on requirements engineering and business analysis1, which also provided the background for my previous article on this blog.)
It is all too common to see texts that flash fancy graphics at the reader without taking care to define the precise meaning of the conventions being used. Such "boxes and arrows" diagrams are particularly common in networking, as in the figure below from Wikipedia, describing components and connections of a "Service-Oriented Architecture".
This example typifies the problems found in many graphical illustrations:
Such pictures, as strong on impressiveness as they are weak on precision, are common in technical documentation.They are prized because they give the reader a quick grasp of the structure of a system. This impression can, however, be deceptive.
When using illustrations of this kind, we should pay particular attention to the connectors between elements of a diagram — typically, lines or arrows of some kind.
Too often, diagram authors include an arrow to indicate that component A somehow relies on component B, or interacts ("talks to") B in some way, or knows about B, or uses B, or is just related to B in some unspecified way. Such vagueness is inappropriate in any technical document intended to have an effect on system development. "Beware of boxes bearing arrows."
Pictures can do more harm than good unless they explicitly state the meaning (the semantics) of all graphical symbols.
Along with arrows connecting components, the symbols representing the components themselves need to have a precisely specified semantics. If you are variously using squares, rectangles, ellipses, circles and other shapes, make sure they correspond not to your whim but to distinct concepts, each explicitly stated.
We will never now whether illustrations following such a discipline would have satisfied Dijkstra, but at least they have a good shot at helping rather than confusing readers.
 Bertrand Meyer: Handbook of Requirements and Business Analysis, 2021, to appear.
Bertrand Meyer is professor and provost at the Schaffhausen Institute of Technology (Switzerland), a visiting professor at Innopolis University, and chief technology officer of Eiffel Software (Goleta, CA).
No entries found