📚 Communication Patterns

Communication Patters - about the book #

Successful communication is the art and science of sharing or exchanging ideas and information, using a common set of symbols, signs, or behaviors, resulting in shared understanding. — Jacqui Read, Communication Patterns ¹

Communication can be hard, and the cost of miscommunication can be high. Refining existing communication patterns into named patterns can form a toolbox for good communication and awareness of dark patterns.

A Pattern is a reusable solution to a commonly occurring problem within that is known to be effective. An Anti-pattern on the other hand is a solution that looks right, but its consequences outweigh its benefits.

Think about the Users Perspective #

Identifying the audience / user to communicate with is key to successful communication.

• What Role does the User fulfill? How much technical knowledge does the User have? Can they understand technical terms, or technical diagrams like UML?
• What does the User want to know? What do you want from the User? In what level of detail do they need the information?
• What do they already know? Do they might know outdated information that needs to be corrected?

Visual Communication #

Which diagram to choose? #

Giving the following bad example:

❌ Anti Pattern: Choosing the wrong Diagram for the User #

Different Users will understand and appreciate different diagrams. Talking in stereotypical roles, the steak holder who wants to understand the system would prefer a User Journey over a Class Diagram, while a Developer would probably gain quite some information from the latter.

The goal should be to choose a diagram that the User is familiar with, that will match their question or conveys the message they should receive, and it should contain the amount of detail that the User needs.

❌ Anti Pattern: Mixing Levels of Abstraction - 🛠 Tool: C4 Model #

Developer Example:³

def feed(corgi: Corgi) -> None:
    # easily readable level of abstraction
    if corgi.is_fed():
        return
    food = _get_food()
    corgi.ate.appent(food)
    # awkwardly detailed level of abstraction
    corgi.last_fed = datetime.now()
    corgi.save()
    # the last 2-3 lines could have been a method,
    # making this much more readable. 

Every diagram will be an abstraction of something, but not everything that can be useful for the reader should be compressed into one diagram. Individual tickets do not belong into a roadmap, as it would clutter the model or even raise the questions what these little details mean if they are so important to be mentioned here.

One Solution to this is offered by the C4 Hierarchy of abstractions. Starting from a big picture it starts with the System Context in which the system interacts with its environment. The Container level displays the components of system with their interaction in between them or the external entities. While the Component levels zooms into one Container of the last level and dissects its subcomponents. The finest level is the Code, which reveals actual implementation.

🏅 Best Practice: Representational Consistency #

When working with multiple diagrams, for example after applying the C4 Model, all references to the same component, role, entity should be easily identifiable as the same. With diagrams, we often do not have the luxury to step in and out of details with one click or having a compiler checking that naming is consistent over multiple diagrams. A role could be named the same and use the same pictogram; a component could be named the same and be framed by the same symbol and color in a system context diagram and a container diagram.

💡 Best Practice: Single Responsibility #

This commonly known software pattern describes that a building block should only have a single responsibility. The most repeated reason for this is maintainability, as there is also only one reason to change; giving a block of code a single responsibility makes it wat easier to understand. The same applies to diagrams, if a diagram tries to convey multiple messages, it will be hard to understand and less effective in conveying that message.

The main differentiation of responsibilities are between Behavior and Structure. Behavior diagrams like Sequence Diagrams show how the system achieves which goal. Structure diagrams like Class Diagrams show what the system is made of and who it interacts with.

Diagram Layout #

After choosing a fitting diagram type, the layout of the diagram should be designed to easily convey the message to the User.

A bad example would be:

❌ Anti Pattern: Boxes in Boxes in Boxes #

Boxes are a great tool to group related items together, if done correctly they can be used to indicate consistent entities over multiple diagrams, e.g. if the box that represents a Component in a Container Diagram is the same as the box that contains a component Diagram. However, boxes within boxes can quickly lead to confusion, and can then cost more time to understand the diagram.

A possible developer analogy might be nested functions, or nesting function logic into multiple levels of classes.

=> White Space reduces Cognitive Load, while lines and boxes increase it.

❌ Anti Pattern: Relationship Spiderweb #

The connection between diagram elements should have a defined meaning, which should be consistent over the diagram and easy to be identified by the User.

Examples of Relationships are:

• Hierarchical: Illustrating parent-child connection, like in taxonomies or organizational charts.
• Sequential: Progress of steps or stages, like in flowcharts or step-by-step guides.
• Causal: Showing cause-effect relationships, like in decision trees.
• Spatial: Representing physical or conceptual proximity, like in mind maps.
• Proportional: Indicating relative scale or size, like in pie charts or bar graphs.

Mixing multiple types of connections or not planning the layout to avoid crossing lines can quickly lead to a spiderweb of connections that is hard to understand.

🏅 Best Practice: Create Visual Balance #

Balance is a innate human expectation. Similar to photos, a diagram that is visually balanced will be easier to understand and appealing to look at. There is no character limit or maximum lines of code per file for diagrams, and fiddling with mermaid directions to achieve a visually balanced diagram can be annoying, but it is worth the effort.

💡 Best Practice: Match the Flow the User Expects, Tell a Story #

A human will find a diagram easier to understand if the flow of information matches their expectations, providing a start point (of a user journey, a state machine, the main class things evolve around), evolving around the message or story the diagram should tell, and a conclusion or end point.

While there are cultural differences, western cultures will expect information to flow from left to right and top to bottom. Anyway, it is easier to follow a flow that is consistent throughout the diagram, and if possible unidirectional.

Diagram Elements #

🏅 Best Practice: Balance Text #

Big walls of text obfuscate the message of a diagram. Often test can be reduced or moved into a footnote or legend.

Like Code, Diagrams should be understandable without comments or additional explanations. Good naming, understandable composition, carefully chosen colors and style, and known symbols can aid a well formulated diagram message.

🏅 Best Practice: Add a Legend #

Not including a legend means assuming that the User understands all elements, abbreviations, or symbols used. That assumption will in the end reduce the audience of the diagram, not only because Users unfamiliar with technical knowledge will not understand it, but also Users of other cultural backgrounds might interpret symbols or colors differently.

❌ Anti Pattern: Color Overload #

Colors should have a meaning - Using too many colors can quickly lead to confusion. Colors are a great tool provide an additional layer of information, e.g. grouping related items, or indicating status, risk levels, or role.

It is a best practice not to rely solely on colors to convey information, and always use a pattern or at least color hue to differentiate items, and included their meaning in the legend.

💡 Best Practice: Use Meta Style #

Style can also convey information. Using a dashed border for deprecated items or a scribbled style for ideas or future features. While many choose a style based on personal preference, choosing between Excalidraw or Mermaid can convey much more information than taste. Every Shape can have meaning by convention or association, and can be much more than style.

❌ Anti Pattern: Misleading the User #

Dark Patterns are well famous in UX Design, but can also be applied to Diagrams. Starting an axis at a non-zero value, using non-linear scales, emotional colors or pictures to influence the User … Every diagram has a message to convey, but misleading the User is plain unethical.

Written Communication #

🏅 Best Practice: Big picture first #

As a User of written communication, knowing the order of the things I am going to learn, will help to organize the information into my mental model. Starting with the big picture provides a narrative, helping to navigate into the details a user might look for and improves retention of information.

🛠Minto Pyramid: The Minto Pyramid Principle is a technique to structure information in a way that is easy to understand.

1. Start with the key message. For the User it is easier to understand the details if the key idea is known upfront.
2. Write out the details of information to convey with the message.
3. Group related information together, and structure them again into key messages and details.

❌ Anti Pattern: Testing the Audiences Knowledge #

The goal of communication is to convey a message. Any word, phrase, or concept that is unknown to the Audience but used by the communicator will make it harder to convey the message. It is important to know the Audience and what knowledge to expect from them in regard to technical terms, domain knowledge, language skills / vocabulary, diagram standards, and cultural context.

💡 Know about Biases #

Humans show systematic patterns of deviation from rationality in judgment, known as cognitive biases. They can affect how important we perceive information, how we interpret messages, and how we make decisions based on what we read or hear. As communicators, being aware of these biases can help us craft messages that are clearer and more effective.

🏅 Knowledge Management Principles #

• Product over Project: Keep the long term focus on domain knowledge that lives beyond the life cycle of a project.
• Ensure Visibility: Make knowledge accessible to those who need it. Centralize documentation in a known location, with open access for people even from different teams if they work on the same product or domain.
• Enable Reusability: Templates and standards for documentation can help to create consistent and reusable knowledge artifacts, while also decreasing entry barriers for contributors.
• Prioritize Searchability: Structure documentation using Metadata, Tags, and a clear structure.

🏅 Best Practice: Get Feedback #

Getting feedback from the multiple Audiences is crucial to successful communication. It is the best way to identify errors and possible optimisations early, establish a dialogue with the Audience, align expectations, evaluate risks, and share the load of communication and documentation. Like Pull Requests in Software Development, having a review process is an effective way to ensure quality and establish shared ownership of communication artifacts.

Conclusion #

Looking at the parallels of modeling a system as code and modeling a system in visual communication provides very interesting point of views. Modern code is designed to be reused, easy to understand, and easy to maintain. Why not apply the same principles and patterns to communication artifacts as well?

The book also covers much more information about verbal communication, meetings, and presentations, goes into great detail about the individual patterns, and provides many more examples - after all these are just my personal takeaways, biased by the knowledge I already had and the ignorance of topics I currently do not appreciate.

Happy coding :) (and communicating)