Style Guide for Semi-Formal Software Architecture Diagrams
- Use arrows to represent data flow.
- Make arrows pointing to the initiator dashed.
- Explain (1) and (2) on the diagram.
- Include a title and date in the diagram.
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.
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.
