[orthoxerox]

The 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.

[HotGarbage]

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.

[kqr]

This is an older discoery than that. Expert systems back in the day often modeled knowledge as graphs with the arrows being labeled with the specific relationship between the things.

It works because (node, edge, node) triplets then form propositions, the fundamental units of knowledge

Come to think of it, expertise researchers still do this today to make rough sketches of domains of study. The result is called a concept map.

[cenamus]

C4 is great, even if I can't be bothered to model every layer

[StrauXX]

You shouldn't! The official writings explicitly discourage creating third and fourth layer diagrams!

[amelius]

This is what I like about electronic circuit schematics: there is only one way to interpret them.

Unfortunately, the exception is in the "functional block diagram" sections in datasheets, where a more loose format is used.

[NalNezumi]

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

[orthoxerox]

One company I worked for solved this by agreeing on "triangle-headed arrow ⭢ means control, barbed arrow 🡒 means data" and putting this into the legend. "Calls REST endpoint to get customer data" would then be a double-headed arrow.

[SoftTalker]

Colors are not an adequately accessible differentiator.

[thomas-mc-work]

Why not?

[yzydserd]

color vision deficiency

[ellyagg]

Use an accessible color palette

[sly010]

There is in fact a 3rd: build time dependencies.

Control: Object/module/function A calls object/module/function B.

Data: The call can either push or pull data.

Build dependency: The call can be direct (A depends on B) or indirect through an interface/callback/etc (both A and B depends on the interface).

Ideally every design document includes all 3 as separate diagrams.

[sly010]

Then of course there is the whole fractal nature of software. As you add more detail, the arrows can flip flop around. Polling in a lower level of a stack can very much be used as a push mechanism. (e.g. USB interrupts are in fact the host polling the device)

This is why communicating architecture is often as hard if not harder than implementing it.

[zabzonk]

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.

[growse]

I do similar, but frame it in terms of dependencies.

The database can live without the web server, but the web server doesn't work without the database.

Therefore webserver ---> database.

Key thing in that these deployment / context / container diagrams don't have a temporal axis. If you want to represent a flow, then you want a diagram where time has directionality, like a sequence diagram.

[segmondy]

yup, A interacts with B with the interaction originating from A.

[chrisweekly]

related tangent (outside of diagrams) lt < and gt > symbols are often dangerously ambiguous; does

    A > B > C  

mean "A then B then C"? or "A is superior to B which is superior to C"?

[zabzonk]

Which (I think) is why we prefer to use "A --> B" rather than "A>B" or "A > B"

[brazzy]

That is just a gigantic failure to provide exactly the information that is needed for such diagrams to helpful.

Basically you're leaving it vague because you can't be arsed to actually work out what it means, and every reader is invited to come up with their own individual wrong assumptions and misunderstandings.

[pepperoni_pizza]

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.

[jollyllama]

Yeah, you're gonna need separate sequence diagrams.