Chapter 4. Narrative
After nourishment, shelter, and companionship, stories are the thing we need most in the world.
Philip Pullman
The term narrative may remind you of an English literature class, but stories serve as a means for so much more, including social bonding, problem-solving, and entertainment among others. As humans, we thrive on stories.
The other chapters in this part are more about what to show your audience to communicate successfully; this one is more about the how. This chapter will help you tell your audience a story to get your message across.
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
Diagrams do not exist in isolation; they are part of a narrative, and the big picture comes first pattern helps order that narrative. Most diagrams are not the beginning of the story, and many are very much down in the nitty-gritty details of design.
Even if your audience is interested in the fine details, that is not what you should show them first. They need the context and to be engaged and hooked into your narrative. Fine details are boring and confusing when you don’t know the big picture. The levels of abstraction discussed in “Mixing Levels of Abstraction” need to be ordered to make sense. When you’ve been delving deep into the details of a project, it’s easy to forget that you should first give your audience context and explain the big why.
Imagine creating a presentation or document about a customer viewing media in an online system. Would you start with Figure 4-1 or 4-2?
Figure 4-1. Data flow diagram—level 2
Figure 4-2. Data flow diagram—level 1
Figure 4-1 shows the detailed process of viewing the media. That is where you want to get to eventually, but it is not where the document or presentation should start. Before going to a level 2 data flow diagram, you need to give context and show the level 1 data flow diagram, such as Figure 4-2.1
Starting with level 1 is a move in the right direction but still doesn’t provide context. A high-level architecture or context diagram, such as the one in Figure 4-3, is where to start. You should also include other supporting materials such as business context and benefits (or at least a summary and links to the full versions in the document or presentation appendix).
Tip
You may not need to spend much time on the context and buildup to the main subject or diagram you need to discuss. The amount of time and detail will depend on your audience and what they already know.
You can then move on in the narrative to a diagram such as a C4 container diagram, if needed, to explain the next conceptual link to the audience, before moving on to the data flow diagrams. You are leading them through a story via the diagrams, with each level adding more understanding.
When you don’t give any context, you lose your audience and are unlikely to get your desired response. Your diagrams and supporting materials (such as requirements, business context, and business benefits) need to be ordered in such a way as to create a narrative, starting with the big picture (like Gregor’s LEGO pirate bay with sharks).
Tip
Put all your diagrams into a narrative order. Are there any holes in your narrative? Fill in those holes before you fall into them in front of others.
Figure 4-3. C4 context diagram
Match Diagram Flow to Expectations
The match diagram flow to expectations pattern enables you to create a diagram that is easy for your audience to read from start to finish. Many people create diagrams without thinking about how the audience will read them. All diagrams have a flow of information, whether they communicate structure or behavior, that you want to match as closely as possible to the audience’s expectations. While other patterns have covered what to include or exclude from a diagram, this pattern is about using those components to order a story in a way that makes sense to your audience.
When you pick up a book, you expect the text to start in the top left and finish in the bottom right (or top right to bottom left if you are reading a right to left language). So why would this not be so with a diagram? Successful communication breaks down as many barriers as possible between you and your audience.
The flow isn’t quite as simple with a diagram as with a book, but having a focus or the start of your diagram in or near the top left, or middle left, makes a lot more sense than starting somewhere else on the canvas for those using languages written from left to right. Follow this with a general flow top to bottom and left to right to aid your audience in consuming the diagram’s message.
Tip
To avoid confusion, especially in a diagram that you cannot edit and rearrange, you can add a label or symbol to show where the audience should start reading. Start here, or a symbol such as an arrow, pointing finger, or Play button are all options. You can also use numbered labels to draw the audience through the diagram in the correct order.
Figure 4-4 illustrates how a data flow diagram could end up if you don’t consider how the audience will read it. Where should they start? The top left is the natural place, but the start is actually closer to the bottom right at the Customer box. The flow is then right to left and bottom to top, going against the audience’s expectation.
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).
Figure 4-4. Data flow diagram with no consideration of how the audience will read it (antipattern)
Figure 4-5 rearranges Figure 4-4 to better indicate the direction of flow. Read through to see how much easier this is to follow. The start of the diagram is on the left (Customer) with requests flowing left to right and responses flowing right to left. The numbered events acting on the data flow top to bottom and left to right, along with the letter identifiers (A–C) of the databases.
Figure 4-5. Data flow diagram matching the left-to-right, top-to-bottom flow of English text
Another aspect of a visual’s flow to consider is the interactions it depicts (for example, labeled relationship arrows). A request should follow the same direction as text (left to right in English), and a response should flow in the opposite direction.
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.
Getting the flow correct is easy in sequence diagrams. The flow starts in the top left and requests flow left to right and responses right to left. Figure 4-6 illustrates a sequence diagram with a flow that meets audience expectations. The order of the components along the top is critical to allowing the flow from left to right and then right to left.
Tip
Explain your diagram to someone (or even to a rubber duck) to check whether your explanation flows across the diagram or jumps about.
Structural diagrams should have a similar flow of information, but require additional considerations. When creating a diagram that includes infrastructure, such as databases, the general expectation is that the infrastructure elements will be placed at the bottom of the diagram, with elements such as systems and containers above, and then elements such as actors or users at the top. This is not a hard-and-fast rule, but it should be followed unless doing so means you fall foul of antipatterns.
Logical diagrams showing, for example, a layered architecture should follow the left-to-right and top-to-bottom flow but also take into account the layers. Similar to other structural diagrams, layers should be arranged logically from top to bottom, with the user-facing layer at the top (such as the user interface or API layer). Within the layers, consider the most logical way to lay out elements from left to right.
Note
Layout expectations differ a little for a hexagonal architecture diagrams. Think of the diagram more like the face of a clock. The top left is still a good place to start because this is where people’s eyes may naturally fall, but you could also draw their attention to the center. Use color, bold/larger text, or thicker lines to draw their eyes to where you want them to start and lay diagram elements out logically in a clockwise direction.
Clear Relationships
A diagram has two main elements: components (containers, processes, and so on) and the relationships between them (arrows, groupings, and so on). Both are critical to the message in a diagram, but relationships lead the audience through a story, and that is why the clear relationships pattern is important.
Without clear relationships, your message gets lost or confused, which could lead to consequences such as:
-
The design you give developers is not implemented the way you wanted it to be.
-
You don’t get budget approval for the changes you want to make to the system because key stakeholders did not understand how those changes would add value.
It is best to have unidirectional (one-direction) relationships, and the label on any arrow between two components should describe the relationship in the direction shown. A line with arrowheads at both ends should be used only when the same process truly does happen in both directions. This is fairly rare.
Relationships can also be made clearer using pattern and color—for example, a dotted or dashed line for an arrow or a box.2 You’ll then need to include a legend.3
Sequence diagrams, such as Figure 4-7, are a good example of unidirectional relationships and flows. Don’t create a sequence diagram like Figure 4-8, which combines each pair of unidirectional relationships into one bidirectional relationship. Compare the labels in Figures 4-7 and 4-8 to see how much information is lost. The message of the diagram is not clear when bidirectional relationships are used, and adding more information to the labels would reduce whitespace and clarity.
ArchiMate, an open modeling language for enterprise architecture, defines many types of relationship via various combinations of patterns and shapes. This notation is good for communicating a large amount of information in a small space, but it requires a legend because the audience might not be familiar with the notation or remember every detail.
Figure 4-9 shows a key to the types of ArchiMate relationships. Including a key (showing at least the types used in the displayed diagram) is needed whenever you create an ArchiMate diagram, to ensure that your audience understands the many types.
Figure 4-9. ArchiMate relationship key
ArchiMate is a perfectly valid notation to use, but consider your audience’s needs. Another notation, such as C4, could communicate your message in a much simpler way without a key (although including a key is nearly always a good idea). I’ll discuss trade-offs with regard to notation further in Chapter 5. Make the story that your relationships tell clear and easy for your audience to understand.
Summary
Throughout this chapter, you have learned techniques for creating flow and narrative in your diagrams to improve audience understanding and keep their attention. Along with the patterns and antipatterns from previous chapters, you now have a large toolbox to draw from when creating diagrams, but there is still more to add.
In this chapter, I introduced notation, which is the system of symbols used to create your diagram and convey your message. The next chapter dives into some antipatterns to help you spot when, and when not, to apply some of the common notations in use today.
1 See Figures 1-10, 1-11, and 1-12 in “Mixing Levels of Abstraction” for more on levels of abstraction such as these.
2 Ensure you avoid the relying on color to communicate antipattern (see “Relying on Color to Communicate”).
3 See “Include a Legend” for more on this.
Get Communication Patterns now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
