Not Worth a Thousand Words

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 analysis¹, 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:

• What exactly does it mean to have a particular layer (such as “Services”) above another (“Data Services/Messaging”)? What is the implied relationship between them?
• Specifically, what is the meaning of the white connectors between layers (the ones that look like tadpoles caught in a snowstorm)? If there is a general rule that each layer relies on the one immediately below, why are there three connectors between “Process/Orchestration” and “Services” just below and just two between “Monitoring/Event Management” and “Process/Orchestration”? Why do some connectors go through intermediate layers, such as from “Process/Orchestration” directly to “Data Services/Messaging” and from “Services” to “Legacy”? Are these cases violations of traditional information hiding rules?
• Why do some elements, such as “Legacy,” appear twice? Presumably there may be more than two “legacy” elements, and (at the same level) more than one “data” so the repetition might suggest elements that appear repeatedly, but are we to understand then that there is only one of “New Services” and of “Internet-based services”?
• The layers are of different nature. The “Data Services/Messaging” layer offers APIs (program interfaces) for certain network services. “Data Abstraction,” on the other hand, is just a general methodological concept. Layering up apples and oranges is confusing.
• The role of the vertical boxes on the sides is unclear. They appear to suggest that Security and Governance apply across all levels (they are “cross-cutting” concerns). Since it is hard to think of an endeavor of any kind in information technology — or, for that matter, any other field of human ingenuity — in which this observation does not apply, it seems hardly essential to the specification of Service-Oriented Architecture. Assuming the boxes did merit their spots in the figure, their placement is puzzling: does Security cease to be a concern for the lower levels, such as “New Services,” to which the box does not extend? Why is there a tadpole from “Governance,” a strategic concern, to “repository,” a technical artifact? (Presumably having a repository helps governance, but the repository will also help “Process/Orchestration”, “Monitoring/Event Management” and just about all the other horizontal layers. Puzzling.)

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.

 

Reference

[1] 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).