Diagrams and Clarity (Threat Model Thursday)
Diagrams serve needs, and surprisingly, form follows function
Why can’t we take a picture of the whiteboard, have an AI make it pretty, and be done? Sometimes this works great, other times it doesn’t, and the deciding factor is what kind of diagram you drew. This has been implicit, and I make it concrete here (and in the new edition of Threat Modeling).
We draw different diagrams to answer “what are we working on.” They are:
- Exploratory
- Explanatory
- Design
- As-built
- As-operated
An exploratory diagram is usually drawn on a napkin or whiteboard. It’s a transient document, focused on a specific decision that needs to be made. They’re narrower and more tied to the conversation that’s happening than explanatory diagrams which substitute in for design or as-built because those diagrams either don’t exist, are overwhelming because they lack a context diagram, or are unavailable in the meeting for some reason, like being hard to find, or too secret for the meeting. Whiteboad diagrams can be either exploratory or explanatory.
The fact that both are drawn on whiteboards makes them easy to think those are the same kind of diagram, and that drives surprise when the AI cleanup isn’t enough.
Design docs or as-built documents are usually more polished than whiteboard documents, and they, or some subset of them, may even be customer-facing, which usually correlates with a lot more polishing. Some organizations have “as operated” or “as maintained” documents, and the later will often focus on configuration and interconnection (IAM, log management, archive/backup, partner data flows).
Studying the diagram for what it contains, the level of polish, and other clues can tell you what the diagram is, but why would you make that a quiz? You can include the type of diagram in the title or title block. For example: “Bikes as a service (Context diagram) (Design).”
Diagram titles are a great tool, and they’re easy to miss. What’s more, it’s easy to miss the value of a title block, including dates, versions, approval, and a link to other documentation or diagrams.
The different sorts of diagrams are less well-known than the different levels, such as context, level 1/2/3, or if you’re a C4 shop, container/component/code.
All of this (and more!) is covered in the mostly new Chapter 3, “Models and Diagrams” of the forthcoming second edition of Threat Modeling.
Image by Gemini, iterated prompting.`