If you’ve worked with complex technical system designs you’ve undoubtedly been exposed to “conceptual” diagrams which aim to introduce the main components of such systems. These diagrams are usually composed of layers of boxes on top of each other which attempt to list each system component, show levels of abstraction, and document the relationships between elements. Although such diagrams are easy to create and often look really cool, the vast majority of them are often more confusing than they are informative.
The reason why such diagrams fail so badly is that they’re simply too abstract. For example, a group of boxes at the bottom of such a diagram usually represent “low level” entities such as hardware elements, while boxes above them are supposed to represent “mid” or “high-level” entities such as drivers and applications.
Although such diagrams are good at listing each component in a system, they tend to miss out on explaining what each component actually is. For example, a box may represent an executable that is loaded by an operating system, but doesn’t actually express that the component is an executable. Instead the name of the component is present but the type is left out creating an abstraction that makes it difficult for the reader to understand what exactly the component is or represents.
In addition, the relationships between components also tend to be missing, or if they are included, are not explained well. For example, boxes in a diagram may be placed above other boxes to show that higher level entities are somehow related to the components of the lower level boxes. However, the relationship is not always clear and could have many meanings thus leading to many questions by the reader: Do the higher level components “use” the lower level components? Do they “inherit from them”? Or do they perhaps contain or simply load the lower level components? There are many types of relationships possible, but are they seldom explained in such diagrams and the reader is left to infer what those relationships might be, a task made even more difficult when they don’t know what the types are for the components themselves.
Thankfully the solution to these problems is simple: don’t be abstract. Introduce elements for what they are (e.g. binaries, object classes, executables, hardware components etc.), and explain each and every relationship.
This may require that components and their relationships be introduced separately in smaller diagrams instead of one large diagram trying to depict the system as a whole, but readers will be able to better digest information this way, especially since elements are introduced one at a time.
And when it comes to showing relationships between components, be sure to use arrows linking each box instead of relying on the placement of boxes relative to others, while explaining each and every arrow with bullets so the reader understands what the relationship is. Information in these bullets can be as simple as a statement like “uses a”, “has a”, or “loads” to explain the aggregation or actions which make up the relationship, or can be brief sentences. Further clarification can be also be added by using icons instead of plain boxes to help provide a visual queue about a component’s meaning where possible.
On a similar note, don’t use terms interchangeably. Often times conceptual terms are used internally by team members to refer to both specific components within a system as well as abstract terms describing a collection of components. Instead try to stay specific by limiting the usage of a term to just the concrete component that it refers to. Only when the reader understands what concrete element or collection a term refers to can it then be introduced more abstractly and even then, this must be done explicitly and carefully to avoid confusion.
The key take away of this short article is to always stay concrete and avoid abstraction when introducing elements to readers. If you find yourself creating conceptual diagrams with boxes on top of boxes, remember that such diagrams tend to fail in their purpose because audiences usually learn new things best by building on existing, concrete knowledge.
If you can break things down and explain them in terms that people understand, while explicitly showing and describing relationships, you stand a much better chance of introducing your audience to the vast collection of components which make up today’s complex systems.