Style Guide for Semi-Formal Software Architecture Diagrams

Posted on October 3, 2021 by Brian Jaress
Tags: advice, reference, people, notation, data flow
  1. Use arrows to represent data flow.
  2. Make arrows pointing to the initiator dashed.
  3. Explain (1) and (2) on the diagram.
  4. Include a title and date in the diagram.
Example of a Diagram Following the Style Guide

I’m writing this down as a reminder to myself, and the phrasing of this whole guide is prescriptive and definitive for quick reference. If you have a different style, great! Use it. I’m making this public to help those who just want some instructions and advice.

Which Diagrams Are Semi-Formal

These diagrams don’t strictly follow or rely on readers knowing the detailed rules of a formal diagramming language but are also not just pictures. They borrow basic concepts and approaches of formal diagramming, usually from system context or sequence diagrams, and try to be more precise than something informal would be.

Why To Be Careful About Arrows

The meanings of arrows are often lost when one person reads another’s diagrams. Some authors use arrows to represent data flow, but others use them to represent actions – pointing from the subject to the object.

It is hard to figure out how an author is using arrows without already understanding the topic presented in the diagram. Sometimes, authors will use both data flow and action arrows in the same diagram. That is one of the most confusing things you can do.

Why To Make Data Flow More Obvious Than Actions

When actions cause data flow, that’s generally the reason for the actions. Actions are also constrained by data flow, since you can’t act on data unless you have it. So data flow is about constraints and goals: the constraints that parts of the system impose on each other and the goals that they have for helping each other. That’s a better introduction for outsiders trying to get an overview.

Example Showing Importance of Data Flow

In the example above, the position and orientation of the data arrows show that mail ends up with the recipient and that the mailbox is an intermediary. The passivity of the mailbox, the fact that it never initiates anything, is a more detailed piece of information shown by using a dashed arrow.

Requests Can Be Data

Technically, requests are always data, carrying at least the information that a request is being made. But whether you give a request its own data arrow is a question of how much detail you want to show.

When you’re tempted to switch to an action arrow, try splitting the connection into separate request and response data arrows. Within each of the two arrows, data will point in the same direction as action. I do this in sequence diagrams to help the reader trace cause-and-effect over time. That makes sense, because time and cause-and-effect are tricky, so I’m explaining them by breaking things down.

As you can see in the final example below, the requester is the initiator of any request-response pair.

Example Sequence Diagram Showing Request as Data