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.

Idk, while system architecture diagrams look cool and feel informative, I generally don't feel like they actually help you get started working somewhere on a project. Mistake #3 in this article, putting too much in, is part of this.

So https://www.jerf.org/iri/post/2025/on_layers_and_boxes_and_l... is an interesting take: put links in your diagram, so it functions as a table of contents. This seems most useful for someone who needs to start working on a project.

Similarly https://haskellforall.com/2026/02/browse-code-by-meaning asks how to show what's in a repo, but maybe file tree is not best and a diagram with links as table of contents is the answer.

That said practically speaking, I'm not sure what tooling easily creates working links in a diagram that looks good in any context, for instance mermaid might render on github but not a text editor.

Of course for other purposes maybe just go crazy with the diagram. I once had a coworker draw this super detailed master diagram, maybe 50-100 things on it, which I was told impressed senior government officials (after my manager recolored all the red to avoid connoting errors). But for the purpose of orienting developers a table of contents with links sounds better.

The biggest mistake is not knowing your audience.

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.

This is just an advertisement for their service.

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.

Couple of comments:

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

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.

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.

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

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.