Diagram Style (Threat Model Thursday)
What makes a diagram good or useful?
What makes for a beautiful and useful diagram? That’s an important question, and one that we often touch on in training, as some folks create diagrams that are beautiful, and others create ones that are... hard to read. And beauty isn’t the only quality we want, and perhaps isn’t even the best name. Beauty is a function of readability and style, and good diagrams go beyond readability and style by following some rules about what they incorporate and how they show it.
Specific and actionable advice for how to make a diagram readable and usable are an important addition to the new edition. The full discussion spans several pages, and below are excerpts from the lists in Chapter 3 of the new edition of Threat Modeling:
Readability
- Align with how we read. In many places, people write from left to right and top to bottom, so draw the same way to align with Western reading norms. (Adjust as needed if you work with other cultures.)
- Limit use of off-diagram references such as “A1” or “T3” that lead to head swiveling or page flipping.
- Label the unusual. If most connections are encrypted, specify that and mark the ones that are not.
- Keep lines short. Short lines are easier to follow.
Style
- Fan in, fan out. Often, a central element of a diagram (“the system” or a dispatcher/queue manager) has many clients or connects out to many places. These fan in or fan out, and putting an element in the center, with clients on the left and the servers it talks to on the right, makes sense.
- Calmness is valuable and hard to achieve. A calm diagram carries a subtext of “We worked on this for you.”
- Diagram elements of the same size, on a grid, are calmer.
- Straight lines are calm, and they become less calm with each bend.
- Lines that cross are less calm. Swapping the placement of elements is a good technique for reducing line crossings.
Rules
- Use unique labels. If you have three elements labeled “server” in a diagram, the label should be more specific. If you have several identical servers, you can use offset stacking.
- Boundaries are explicitly shown for (at least) data centers, cloud providers, client devices, and other zones of administrative control.
- Only data flows cross boundaries.
Using a diagram entails understanding it and then using it to either ask or answer questions about the represented system. The harder the diagram is to understand, the more work is needed to get any value.
Diagram effort includes creating, refining, redrawing and interpreting a diagram.
Return on effort is a major theme of the book. Thinking about the work we put into either creating or using a diagram lets us ask “is this next increment worthwhile?” “To whom is it valuable?” and “why would it be valuable?”
As I talked about in last week’s post, the effort involved increases as you go from an exploratory diagram to a diagram of record.
A diagram that’s pleasing to the eye is one with a clear purpose, and that’s easy to use as we implicitly or explicitly trace how a system works. A diagram where someone has shown care in making it readable communicates that this is important enough to do well. That effort pays off for the users of the diagram mainly because they work faster, but also because you’re showing respect by having made their work easier.
Image by Gemini, iterated prompts starting from “Draw me a diagram that violates many of these rules.”