Why did we draw this diagram?

What does a software architect do? Sometimes I say to people, I make diagrams with rectangles and lines in between them. If you pay extra, I might even add arrow heads to the lines!

This is only half joking. In fact, many of the artefacts used by software/enterprise architects are diagrams, and these tend to rely heavily on rectangles and lines. But when you say it like that, it sounds a bit shallow and simplistic. Why on earth would anyone spend their working day just drawing some rectangles with lines in between?

And this is precisely the question that some practitioners of software and enterprise architecture don’t stop to ask themselves. Instead, there is much wailing and gnashing of teeth about which diagrams to draw. How many rectangles? Should some of them be squircles, and have different colors? Do we have the same information in a list? (Let’s make sure we call it a catalogue, so it doesn’t sound like it’s a list.) Do we use Archimate or Edgy? Togaf? Aris? Surely we need to create a BPMN diagram of every process?

If you’re involved in a discussion like that, then the focus is too much on creation of artefacts and not on how they will be used.

Coming back to the question, why would you draw these diagrams? Presumably, they will be used to create or maintain software, or for troubleshooting.  

Completionism is a pitfall that you may fall into. We need a complete overview of all processes, integrations, components, etc. The problem with trying to be complete, is that it requires ongoing effort to keep the documentation up to date. Once a system is in production, there will be (formal or informal) additions and tweaks that build up over months and years. In many cases, a complete overview can only be created after-the-fact, by programmatically generating documentation from the actually deployed software. This will also be a very detailed overview, which is something you can’t feasibly create prospectively.

This all raised the question, what might we be creating these diagrams for? These are some possible answers:

• Exploration and discussion. These diagrams are made on white boards typically, and a lot gets wiped out! The most important results are actually the choices made (and why some seemingly obvious alternatives were dismissed)
• Creating a planning. Here, you’d want to have a complete overview, but not necessarily one that is very detailed. After all, finding out the details is part of the work being planned! The most important aspect here is that all of the different areas of expertise are identified, and that subject matter experts in those areas have a clear understanding what will be asked of them – and where their responsibilities end.
• Designing software. The objective here is to identify the features or epics that will be  needed, for some period of time; perhaps the next PI or the next sprint. This will raise questions about integrations; which technology/middleware is involved, are the APIs already available?
• Onboarding team members. The information needed can be very dependent on the role of the new team member, but a general overview of capabilities and applications is almost always a good idea to show.

These are just four topics that spring to mind. How many can you think of? Whichever objective you have in mind, the type of diagram – or the relevant parts – may be completely different. Which brings us to this Tuesday’s Takeaway: the artefacts produced by software/enterprise architects are not just technical diagrams that model reality – they are a tool to communicate. Each diagram has a key message that you’re trying to communicate.

Since it’s a communication tool, you can also think of Barbare Minto’s Pyramid Principle. If we think of the rectangles and lines on the diagram as the base of pyramid, what is the key message (conclusion)? That can be the title when you show the diagram on a slide! And what are the supporting arguments? That’s the “voice over” that’s often not written down, but the most critical part.