Defining a Diagram with a Question


Over the years, I’ve seen plenty of good diagrams and I’ve seen plenty of bad ones. Many, if not all of the bad ones had a certain thing in common – it was hard to figure out what was going on there.

When you create a diagram, you’re doing it to convey information. You can’t convey every piece of information in a diagram, so selecting what you show and don’t show is part of putting the diagram together. A useful way to guide these decision is to be able to say – what question does this diagram provide the answer to?

When you create a diagram, whether it’s a process map, an org chart, or something else, you implicitly have to make decisions. What do you show? Unfortunately, asking this question of the stakeholder is a recipe for non-progress. “Show me everything”. Umm, everything? Shall we start with the individual names of each person who might perform a process and start from there?

In practice, what they mean is “Show me everything that I care about”. Which of course is not very helpful, but I’m hoping that a majority of architects are starting to think in terms of views and viewpoints as a result of that last comment.

To establish a baseline of understanding, one of the most influential standards in architecture modeling is ISO 42010 (once known as IEEE 1471). One of the most pervasive ideas it presents is that you have various stakeholders, who each have different concerns, and so you don’t just present the same model to each stakeholder. Instead, you present a ‘View’ of the situation that addresses their concerns. Each view for a project is an implementation of a viewpoint.

There are several architecture frameworks out there that offer different sets of viewpoints – TOGAF, Archimate, DODAF, MODAF and so on. What I often find that people, even TOGAF certified architects with a couple of years of experience, struggle with is understanding which viewpoint to use when. Each of the above frameworks define what they feel a given viewpoint provides, but often in rather dry language.

The problem with such dry language is that it’s not snappy. What I mean by that is that when challenged by a non-technical executive to explain “so why is this important to someone?”, a dry recitation often doesn’t work. What’s needed is a quick summary, and the best way I’ve found to have one is to define the diagram in terms of a question.

We don’t create architecture diagrams for fun – not in my experience, anyway. The diagram is supposed to provide some level of insight to the people consuming it, and so we can define the diagram by asking what insight does it actually provide. IN other words, what question does this diagram answer? Some examples –

“This diagram shows all our applications, and which ones exchange data between themselves”

“This diagram shows our critical applications, and where they are hosted”

“This diagram shows the flow of control in fulfilling a customer order”.

Most of these statements seem obvious (indeed they are). But it’s when you’re challenged in the heat of a presentation that having this answer pre-thought becomes useful.