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.
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.
In my 20 years in this field I can easily count on one hand the times a diagram like this has been useful. I’ve seen more cases where they were clearly created to satisfy some exec that wanted to see it and never updated again.
And I disagree somewhat that the names are really needed at all
You want a diagram containing only icons? You will still need a legend somewhere that explains what each icon means, otherwise you will end up with at least as many interpretations of the diagram as there are readers of it.
And I'd say that that first image as shown is virtually useless anyway. There is little value in just laying out resource components without linking them to system operation in some way -- which means that that diagram can only be understood in its larger context, and that's typically not how diagrams are used: they end up being the main focus of discussions.
Why? Hungarian notation probably is probably going too far, but in cases where a single word is heavily overloaded encoding types is helpful (eg. image file, image table, image bucket).
I don't think the type needs to be in the name because it is displayed elsewhere in the diagram, possibly as the object's icon. Plus of course the reasons no-one uses Hungarian anymore - types change.
And for your naming, I would probably have something like "Unnormalized orders", "normalised orders", "queued orders", but obviously I can't tell without much more information.
Diagrams are communication tools, and are best done with a target and goal in mind. The C4 framework is good for addressing multiple levels of abstraction and different types of viewers. The business execs don't need the level of detail that someone debugging the system does.
My thought process is that a diagram should stand on its own and should be understandable by non technical business people. I always have callout notes as stickies on the diagram explaining what it does.
The worst ones are diagrams that look clean but hide all the decisions that actually matter. A messy diagram that shows the real tradeoffs is more useful than a pretty one that lies
Once worked with a systems architect who intentionally disorganized their flow diagrams by just moving nodes in their flow to random places (hi Dan!). The only reason I can think of why he'd do that is to maintain job security by keeping the junior apps folk confused.
It amazes me that they are spending all of this time reducing the memory footprint and not do the most obvious thing - just stop using fucking Electron
Their master diagram example in #3 contains a #2 mistake with an unconnected resource (the stripe account). Maybe a double validation of why the master diagrams can be hard to maintain.
Is the diagram for marketing? A sales proposal? A business person using the product? Technical peer?
If you don't know this, you don't know if you have the right level of detail.
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.
Most of the article's diagrams are actually terrible in this regard.
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 my 20 years in this field I can easily count on one hand the times a diagram like this has been useful. I’ve seen more cases where they were clearly created to satisfy some exec that wanted to see it and never updated again.
> This can be as simple as adding a type suffix to a resource name (e.g. Orders Table, Results Bucket)
Don't encode types in names. And I disagree somewhat that the names are really needed at all.
> Making a “master” diagram
I think such a diagram is useful but obviously each top-level "box" in it doesn't need to contain all sub-components.
You want a diagram containing only icons? You will still need a legend somewhere that explains what each icon means, otherwise you will end up with at least as many interpretations of the diagram as there are readers of it.
And I'd say that that first image as shown is virtually useless anyway. There is little value in just laying out resource components without linking them to system operation in some way -- which means that that diagram can only be understood in its larger context, and that's typically not how diagrams are used: they end up being the main focus of discussions.
Why? Hungarian notation probably is probably going too far, but in cases where a single word is heavily overloaded encoding types is helpful (eg. image file, image table, image bucket).
And for your naming, I would probably have something like "Unnormalized orders", "normalised orders", "queued orders", but obviously I can't tell without much more information.