Chapter 1 - Communication Essentials
Limit individual diagrams to a single level of abstraction - think the C4 diagram models.
If multiple levels of abstraction are required to convey the ideas, create at least one diagram per level.
Pattern - Representational Consistency
Use common methods of representation for the same or like concepts between discrete diagrams to help the audience navigate between them. Models like C4 have formal methods of communicating representational consistency (the dashed line to separate a container diagram from the context diagram in which it sits, for example).
Chapter 2 - Clarify the Clutter
Antipattern - Colour Overload
Using too many colours/using colours without any attention to what those colours represent causes the audience to waste mental energy trying to decipher meaning where there is none. Minimise the colour palette, using only the number of colours you need to convey the message. Consider using colours to visual group like concepts.
Antipattern - Boxes in Boxes in Boxes
Too many boxes and lines in a diagram quickly becomes confusing for the audience, and forces them to expend mental energy trying to understand what they all mean.
TIP
Make good use of whitespace. It gives the eyes a place to rest, reducing cognitive load, and it makes the diagram easier to scan.
TIP
Keep background colours subtle to improve the contrast between the background and diagram items.
Use different types of boxes (dashed outlines, shaded boxes) and collapse or remove boxes that are not needed to convey the message. Nested boxes are often confusing, use them sparingly.
Antipattern - Relationship Spiderweb
Relationships between diagram components are often represented as lines. Too many lines, particularly too many lines that intersect quickly reduce clarity. Consider breaking a single diagram into multiple if reducing the number of lines representing relationships is not possible. Shuffle diagram items around to minimise intersecting lines, and where lines must intersect, make it clear which line goes where - most tools have the ability to “line jump”, so use it. Use lines with right angles to add some uniformity to the relationships being described and improve legibility.
TIP
Standardise the position of labels indicating relationships. Make exceptions to this rule only when doing so would clarify the relationship.
Pattern - Balance Text
Too much text quickly begins to obfuscate the intended message of a diagram. We are aiming to strike a balance between enough text that the message is appropriately understood by intended audiences, and too much clutter that the message is lost or only partially understood.
TIP
Supplementary information including information written as sentences is a good candidate to abridge or remove from a diagram into separate text. Relational data is a good candidate to be displayed in table form.
TIP
Reduce redundancy of information in diagrams. What information can be inferred from context?
Chapter 3 - Accessibility
Relying on Colour to Communicate
4.5% of the population are affected by some form of colour blindness, with it being more prevalent in men (1 in 12) than women (1 in 200). Additionally, some people struggle to perceive low contrast.
TIP
Use https://www.whocanuse.com/ to see how colour combinations are perceived by people with colour vision deficiencies.
People viewing diagrams on different monitors or via a projector may see slightly different colours than expected. A green component may appear yellow, for example, and referring to it by the colour green will be confusing.
TIP
Any meaning placed upon different colours is lost if those colours are indistinguishable. A legend is useless in this situation.
TIP
Patterns can be used instead of colour to differentiate elements in a way that is easily understood even in grayscale.
Pastel colours are often not as accessible, because of their lower contrast.
Pattern - Appropriate Labels
This pattern is about making sure text and labels clearly communicate your message. Besides content, consider placement of labels. They should be close to the component or relationship they are labelling (while also being mindful of your use of whitespace).
Chapter 4 - Narrative
Pattern - The Big Picture Comes First
When you look at the cover of a box of LEGOs you don’t see a picture of each individual brick that’s inside. Instead, you see the picture of an exciting, fully assembled model…positioned in a life-like pirate’s bay with cliffs and sharks. Gregor Hohpe, The Software Architect Elevator
Consider how a diagram exists within the context of the narrative you are trying to deliver. A diagram that is zoomed in on a very specific detail of a system is unlikely to be a good starting point for a narrative. Levels of abstraction is the right metaphor here. Construct a logical sequence that starts at the highest level of abstraction, and incrementally zooms in to deliver the narrative.
Pattern - Match Diagram Flow to Expectations
This pattern helps make diagrams that can be easily read from start to finish. When you pick up a book, you expect the text to start in the top left and finish in the bottom right. Creating diagrams that focus attention at the top or middle left, and flow to the right and down to reduce friction for the audience reading and understanding.
TIP
Like a story, your diagram should have a beginning (where the audience should start to read), a middle (the rest of the content in an appropriate order), and an end (the conclusions you want the audience to draw).
TIP
Ensure that a response from a component always flows in the opposite direction of any requests. Visually differentiating types of interactions helps your audience understand your diagram more easily.
Excerpt from Communication Patterns Jacqui Read This material may be protected by copyright.
Pattern - Clear Relationships
A diagram has two main elements: components (containers, processes etc.) and the relationships between them (arrows, groupings). It is the relationships that guide the audience through a story - without clear relationships, any message is lost. Generally we should only be using uni-directional relationships (with an arrowhead at one end). Only if the same process truly does happen in both directions should we show a bidirectional relationship.
Consider using different notation to convey more complex relationships e.g. UML, ArchiMate.
Types of Relationships
You can convey many types of relationships via visuals. Here are five relationship types to consider:
Hierarchical
Illustrates the parent-child connection between elements. It often represents organizational structures or classification systems. Examples include organizational charts, family trees, and taxonomies.
Sequential
Shows a linear progression or a series of steps. It indicates an order or a process that must be followed. Examples include flowcharts, timelines, and step-by-step guides.
Causal
Depicts cause and effect, as one element leads to or influences another. This type of relationship is often seen in flowcharts, system diagrams, and decision trees.
Proportional
Illustrates the relative size, quantity, or scale of elements in comparison to one another. Examples include bar graphs, pie charts, and treemaps.
Spatial
Shows the physical arrangement or relative position of elements. This type of relationship can be seen in maps, floor plans, and network diagrams.
Chapter 5 - Notation
Antipattern - Using Icons to Convey Meaning
If icons are used as the only form of communication, or alongside very little textual information, a chunk of your audience may not understand the message. Use icons only in addition to the information being conveyed - you should be able to remove the icons and still have the message remain understandable.
Using UML for UML’s sake
What are you trying to communicate? Who are you trying to communicate with? What knowledge do they have? We often cannot assume that our audience will sufficiently understand UML to make it a default. Not only this, but potential authors must sufficiently understand UML to be able to update diagrams using it - artificially limiting who can do it, and increasing the likelihood that documentation will fall out of date.
Mixing Behaviour and Structure
Apply the single responsibility principle to diagrams. Structural diagrams communicate the what and where - showing systems and their relationships. Behavioural diagrams communicate the how and to whom - such as the flow of data or state changes within a system. Mixing these two ideas into a single diagram will muddy the message.
Chapter 8 - Verbal and Nonverbal Communication
Encoding messages
Encoding messages refers to the process we go through to package up our thoughts in order to convey them to another person. We can use a few different techniques to help us ensure we encode our messages to give them the best chance of being understood.