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.

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.

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.

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.

To me the biggest issue is keeping it all up to date. For that reason I've completely shifted to text-to-diagram tools like PlantUML / Mermaid. As imperfect as they are, they mean you can insist the diagrams are updated in the same commit (or merge request) as the code, and the AI tools are pretty good at working with them too.

I am pretty frustrated at times though with PlantUML / Mermaid. They just do not give enough power to format the diagrams in a human legible way. Am curious what others do for more complex diagrams in this regard.

As the resident Diagram Maker at my job I really appreciate any and all discourse on the topic. Knowing the purpose of your diagram is a hugely under-appreciated part of the process. Service flow chart or system architecture? High level system overview or actionable, followable flow-chart? The engineer in me always wants to put All The Things in the chart, to make it maximally "correct". It's never the right move. But how to make it clear what's included or not, and why?

I still struggle with finding the best approach each time; I'd love more discussion of this stuff.

One common mistake when pointing out common mistakes: Show the good example!

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.

Most common mistake: Creating diagrams in a graphics program without semantics. Why not write your "diagram" in code or at least some structured format?

- LLMs can read and write it, it serves as valuable context

- Always up to date, rendered on demand

- source controllable

- editable (thus will actually get edited)

Most architectural diagrams I see are just images with no source or semantics. Strictly less useful and more prone to rot.

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 main one i would add is a lack of symmetrical alignment. the point of a diagram is to create a shared abstraction for reasoning about a system or set of problems. The point of that is to scale work on it to other minds. It should enable others to parse it and ask useful questions.

If your diagram is ugly, you're probably mixing levels of abstraction without acknowledging it. It's a forcing function on articulating what you know and what is outstanding. Something that is black boxed should be referenced as a black box.

I use a lot of data viz because it's a high bandwidth way to show relationships, dynamics, order of complexity and its location, information problems, scope, and de-noise data. So much can be explained by having AI make you a uml sequence diagram of a concept. it is unreasonbly effective. If you are making a "chart for management" and using powerpoint or native excel charts, you're probably creating garbage though.

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.

I’ve always used a simplified UML style[0], even for system diagrams. OmniGraffle is an essential tool, for me.

I spell out what arrows and line types mean. I don’t rely on conventions, as I find “pure” UML to be something that most folks don’t know, so I”m basically writing in hieroglyphics.

[0] https://littlegreenviper.com/the-curious-case-of-the-protoco...

> Meaningless animations

As someone who usually hates animations, in the example given I actually find them useful, assuming that they are representative of the actual flow. They are also unobtrusive because they are steady-state.

I generally have given up on diagrams. Systems and flows I work with are too convoluted to be mapped out. Only the simplest of flows can be diagrammed and it usually leaves out important facts. When dealing with non technical people, I have found out through trial and error that excel works best. I start out with sample data on one sheet and walk them through the various transformations in sheet2, sheet3 etc. I even create a table of contents that has links to the different sheets. In a phrase, seeing data is believing.

I really miss a mistake which I see a lot: a simple frontend (the architecture component) talking to backend (also an architecture component). I had to put extra effort all the time to explain the "no, people, a static web server is not sending anything to anywhere, it just serves static files".

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.

Route53 being off on the side but unconnected is still valuable info...

[dead]

[dead]

[dead]

Architecture diagrams are the bane of my existence right now. I sit there and listen to engineers opine on the different types, levels, details, etc. And all I can think is...

What a TERRIBLE way to store information in an AI era. Diagrams are so...human.