alt Hacker NewsThe most common mistake I've seen is not agreeing on what arrows represent: control or data. Does A-(customer data)->B mean A asks B for data or A sends customer data to B?
Of course, sequence diagrams make it clear with two separate arrows when control and data flow in different directions, but a lot of diagrams are of the "plain old boxes and arrows" variety.
Replies
Yup, we had exactly those hangups when diagrams showed data flowing from restricted network system to data lake. The data is generated and owned by the system and the lake has a secondary copy, except the physical implementation is that the lake opens a connection and pulls. Somehow that is forbidden and we spent months fighting firewall people. Fortune 50 is fun.
The one solution that works for me is to color code each arrow and at the top left of the diagram add a legend that describe what each colored arrow represent.
This way sometimes the color can describe control, data, and sometimes even teams expected to implement this arrow by color coding teams.
The latter is very helpful for cross team meetings to make each group focus on the part of the diagram that will affect them the most, and give pointed feedback to assumptions and lack in specs
In high-level diagrams, which I think is what is being discussed here, I like to think that A --> B means that A "uses" B in some way, and leave it at that.
This is why the C4 Model insists on using verbs to label interactions. (e.g. “reads/writes data from”, “sends reports to”, etc).
Most of the article's diagrams are actually terrible in this regard.