Communication Patterns

Chapter 1. Communication Essentials

This chapter provides the foundation that you will build upon with the other patterns in Part I. When I refer to patterns and antipatterns, I mean the following:

Pattern

A reusable solution known to be effective when used to solve a specific or more general problem, which may otherwise be known as techniques, practices, methods, or rules.

Antipattern

A solution that is not recommended. It looks like it is the right way to solve a problem when in reality its consequences outweigh any benefits.

I highly recommend making sure you are employing the patterns and antipatterns in this chapter before building on them with all the others. Think of it the same way as architecting a building: you need to get the foundation right before you can build the walls, floors, and roof. Don’t start building on sand, or your construction will sink. Get this groundwork right first.

Know Your Audience

The know your audience pattern is also known as understanding your customer. One of the essential factors to keep in mind when creating and editing a diagram is who is going to be viewing and reading it. Your diagram’s purpose is to communicate successfully with this audience. Knowing who they are and designing the diagram to their needs are key to this purpose.

People who view your diagram could have the following roles:

• Developers (full-stack, frontend, backend…)

• Architects (technical, solution, security…)

• Business analysts

• Product owners

• Project managers

• Customers

• Support teams

Tip

Make a list of the roles that view your diagrams and then group the roles based on the types of diagrams you create. You will likely find that you have a different audience mix for different diagrams. Use these lists with the questions near the end of this section.

The following diagrams have been created for different audiences, and the type of diagram and notation have been chosen to suit the audience.

Figure 1-1 shows a Unified Modeling Language (UML) class diagram aimed at a technical audience, including developers, architects, and database administrators. A product owner or project manager would be unlikely to need the information in this diagram or be able to understand it without help.

Figure 1-1. UML class diagram, aimed at a technical audience

Figure 1-2 is a C4 context diagram. This is a versatile diagram, useful for both technical and business audiences to get an overview of a system. This diagram is equally readable and useful to roles such as product owner, project manager, architect, developer, and business analyst.

Figure 1-2. C4 context diagram, useful to most audiences

The domain story shown in Figure 1-3 is aimed more at business roles, but also those technical roles that are involved in translating business needs into technical solutions. Domain stories are created to improve communication between business stakeholders and technical roles so that the solution meets the needs of the business and users. Domain or subject matter experts (SMEs) would be involved in creating and verifying a domain story, along with roles such as product owner (if not the SME), business analyst, and architect.

Figure 1-3. Domain story diagram, aimed at business roles and technical translator roles such as architects and business analysts

After identifying your audience, ask yourself the following about them:

What do they want from you?

Consider your audience’s expectations and needs. Meeting their needs is key to successful communication. Is your audience looking for specific information so they can make a decision or report back to someone else? Keep your audience happy by sending them away with the information and understanding they need to do their jobs.

What do you want from them?

This question is often missed: what you need from your audience. Do you need agreement or sign-off on your design decisions? Do you need them to make a decision based on your diagrams? Make sure the audience understands what you need from them and by when, and has all they need in order to meet your expectations.

What is their technical understanding?

Your audience’s technical understanding will determine the type of diagram they will benefit from. Consider how technical your project manager is. Does your product owner want to know about the selected technology, or just about how well the selection meets the requirements?

What level of detail do they need?

Whether the content is technical or not, you need to consider the appropriate level of detail. Is this diagram for an architectural review board that will expect a lot of detail? Does the development team need implementation details, or is determining those details part of their job?¹ Ask teams what they want, rather than going by any written or unwritten guides the company gives you. If there are rules that don’t meet the team’s needs, bring it up with the appropriate person.

Besides these questions, consider that members of your audience may not be native speakers of the language you are using and may have a different cultural background from you (see “Simple Language”).

Once you’ve identified your audience and their needs, you can begin your diagram.

Mixing Levels of Abstraction

Mixing levels of abstraction is a communication antipattern that has a counterpart in the coding world. If you have ever coded, you will likely know mixing levels of abstraction as a sin or a code smell.² Although putting all the information someone could need into one diagram might seem appropriate, this leads to clutter and confusion from the audience’s perspective.

Note

Levels of abstraction refers to the granularity or generality of the information you present in a diagram. Abstraction levels range from high-level views showing the major components of a system and their relationships to one another down to low-level diagrams detailing the code’s structure.

Using different levels of abstraction across multiple diagrams allows you to communicate appropriately for the audience, while still ensuring that all relevant information is captured.

All software is an abstraction, but in essence, levels of abstraction let you hide low-level details from high-level concepts. Developers do not write software using ones and zeros (binary or machine code); they develop by writing in higher-level languages that abstract away the complexities of machine code and all the levels between (interpreters, compilers, and so forth).

Take a look at Figure 1-4. If you think of the process of going to work as one level of abstraction, the next level could contain the concepts of getting up, having a shower, getting dressed, having breakfast, leaving the house, and so on. The next level for getting up would contain pushing back the covers, sitting up, and standing up. There you have three levels of abstraction (going to work, getting up, pushing back the covers), but in software terms, these should all be separate (such as in different methods or classes) to avoid confusion and unneeded complexity, and to aid readability.

Figure 1-4. Levels of abstraction in everyday life

Using levels of abstraction applies to software architecture and diagrams in the same way. In code, you apply this principle to methods, classes, layers in a layered application (such as a presentation layer, the business logic, a persistence layer, and the data store), and more. In diagrams and software architecture, you apply this principle to the content of diagrams and to the structure of services, microservices, and so forth.

The C4 model is a hierarchy of abstractions. It uses an abstraction first approach (prioritizing abstraction and building everything else around it). Its four abstraction layers define its core diagrams:³

1. The system context shows an overview of the system and how it fits into its environment, including interactions between the system and other entities.

2. The container level zooms in on the software system in scope, showing the high-level components or building blocks and how they interact with each other and external entities.

3. The component level zooms in further on an individual container from the previous level. It shows the components inside the container and their interactions with each other and with external entities.

4. The code level zooms in still further on a component from the previous level. It shows how the component is implemented. (This level is often more detail than is necessary in your documentation).

You can think of these four levels as maps that you can zoom in on to reveal increasing levels of detail. The C4 abstraction layers can illustrate the need for varying levels of detail.

Figure 1-5 isn’t a context diagram and it isn’t a container diagram. It is a mix of two levels of abstraction. If you look at the diagram closely, it doesn’t make sense. The system in focus (Polyglot Media’s software system) seems to have been partially divided into containers, and the relationship between the software system and containers doesn’t make sense. The software system and the containers belong in different conceptual levels. In reality, containers within the software system will be interacting with the containers shown.

Figure 1-5. C4 diagram showing both context and container levels of abstraction (antipattern)

Figure 1-6 shows how the context diagram for Figure 1-5 should look. This is where the software system in focus (Polyglot Media) belongs, with its related external systems and actors.

Figure 1-6. C4 context diagram

Figure 1-7 shows how the container abstraction layer information in Figure 1-5 should be shown in a C4 container diagram. The system in focus (Polyglot Media) is shown as a dashed box with the containers inside it.

C4 models, based around a hierarchy of abstractions, are an excellent way to illustrate the need to keep levels of abstraction separate in diagrams. This separation rule applies to all types of diagrams. Apply it to your sequence diagrams, data flow diagrams, diagrams with no formal notation, and all the other types of diagrams you use. All your diagrams should follow this rule; it is essential for communication.

Once you have split up any mixed diagrams so that each has only one level of abstraction, read on to find out how to make them easily navigable.

Figure 1-7. C4 container diagram

Representational Consistency

Using the representational consistency pattern is the next step after checking levels of abstraction: linking discrete diagrams together so that your audience can navigate between them easily and see how they fit together. Understanding how your diagrams relate to one another should be easy for your audience. You risk unsuccessful communication if your audience has to think too much, or remember a key or pivotal detail, to understand relationships between diagrams (each an individual level of abstraction).

Many notations, such as C4 and data flow diagrams, have formal and explicit ways of communicating representational consistency. As noted previously, C4 diagrams also have explicit levels of abstraction (context, container, component, and code). Take a look at Figure 1-8, which shows the system in scope (Polyglot Media) in the center of the diagram. This context level is the highest in C4 diagrams.

Figure 1-8. C4 context diagram

The next level down is a C4 container diagram (Figure 1-9). The method of connecting these diagrams is a dashed box in Figure 1-9, which is labeled (in the bottom left) the same as the central box (Polyglot Media) in Figure 1-8. This allows the audience to see the connection between these two diagrams, whichever one they see first.

Figure 1-9. C4 container diagram for Polyglot Media (showing the high-level interactions within the Polyglot Media system)

In a data flow diagram, you use numbers and letters to indicate the identity of its elements, and then you can use those same numbers and letters to guide your audience through different levels (shown in different diagrams). For example, in Figure 1-10 the processes are numbered 1 through 3 to indicate the order in which they occur, and if those processes are further divided in another diagram, they can be identified by that number.

Figure 1-10. Level 1 data flow diagram

In Figure 1-11, process 2 from Figure 1-10 is divided into three subprocesses. You can tell this because they are numbered 2.1 through 2.3. The processes are again ordered, but relative to the higher-level diagram in Figure 1-10.

Figure 1-11. Level 2 data flow diagram

If you compare the data stores in Figures 1-10 and 1-11, you will notice that the data stores labeled A and B in Figure 1-10 also appear in Figure 1-11 with the same identities.⁴

If the notation you’re using doesn’t provide a formal way of connecting diagrams, you will need to make the connection explicit yourself. For example, Figure 1-12 shows another way to connect process 2 (Fetch media) in Figure 1-10 and its subprocesses 2.1 through 2.3 in Figure 1-11 using a similar method to the one employed by C4 diagrams (shown previously in Figure 1-9). You could use a similar technique in many types of diagrams.

Figure 1-12. Level 2 data flow diagram with explicit representational consistency

Tip

When including diagrams in documentation, refer to them in the text of that documentation. Use hyperlinks if possible, and label your diagrams (for example, “Figure 1: System X context diagram”) and then reference that label explicitly.

Make representational consistency explicit in your diagrams and documentation to reduce your audience’s cognitive load.⁵

Summary

This chapter covered the essentials of visual communication, giving you a foundation on which to build with the remaining patterns and antipatterns in Part I. As you continue through the book, think about how you could apply these essentials along with the other patterns and antipatterns explored.

Having thought about what your audience needs from your diagram, it is time to consider the amount of information that you are presenting in it. Keeping this to the bare minimum needed to communicate your message will improve your audience’s understanding.

¹ The level of detail in designs for development teams can be controversial, leading to clashes between development and those creating the designs.

² A characteristic of the code that possibly indicates a deeper problem.

³ C4 also has some supplementary diagrams such as a deployment diagram.

⁴ Notice that the data store identities (A, B, and so on) are ordered in the same sequence as the data stores are accessed in the flow of the diagram.

⁵ Cognitive load is the amount of effort a person has to exert to reason or think about something.