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.

▲

zahlman 5 hours ago | parent [-]

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

My reaction to the title was that trying to create the diagram is the mistake. If you can't explain it in prose, simplify.

▲

dpark 5 hours ago | parent | next [-]

A picture’s worth a thousand words.

A diagram is a dense way to express information. The same information in prose would take much longer for a typical human to absorb.

> If you can't explain it in prose, simplify.

Simplify what? The system? Usually you can’t just throw things away from the system to make it easier to describe.

▲

vanviegen 4 hours ago | parent | next [-]

> A diagram is a dense way to express information.

I'd say it's a lossy way to express information. I find that architecture diagrams often cannot express the exact concepts I mean to communicate, so you're left trying to shoehorn concepts into boxes that are somewhat similar, and try to make up for the difference using a couple of cryptic words.

Prose doesn't look as nice, but allows me to describe exactly what I want to say, on any level of detail required. Of course, like with a diagram, you do need to put in significant time and effort to make it comprehensible.

▲

dpark 4 hours ago | parent [-]

> I'd say it's a lossy way to express information.

A simplified explanation of the system is by definition lossy. This equally applies to a plain English description.

I’ve been in many design reviews and similar forums where someone has attempted to present a design through written English and finally someone says “we need a diagram here; this is too much to follow” and everyone in the audience nods because they are all lost.

One of the problems with trying to communicate system design with prose is that it makes sense to the person who writes it and has full context, but the audience is often left confused. Diagrams are often easier to follow specifically because they look under specified when they are.

	▲	vanviegen 35 minutes ago \| parent [-]
		> finally someone says “we need a diagram here; this is too much to follow” and everyone in the audience nods because they are all lost. Yes, that happens. I can't remember any occasions where the diagram actually cleared things up though. Coming to think of it, one way that seems to be pretty effective at getting complex designs across is in an interactive presentation with the presenter drawing on a whiteboard, starting simple and adding stuff while explaining what and why. The narrative is very important though. The whiteboard drawings by themselves are absolutely useless.

▲

zahlman 4 hours ago | parent | prev [-]

> Usually you can’t just throw things away from the system to make it easier to describe.

You can't throw away requirements, but sometimes there don't need to be as many moving parts behind the curtain as you think in order to implement those requirements.

▲

dpark 4 hours ago | parent [-]

This is essentially a statement that the system shouldn’t be unnecessarily complex. And sure, but that’s not really relevant to the discussion.

If you have a complex system, whether due to legacy or due to actual necessity, you aren’t going to redesign the system just for the sake of simpler explanation. Indeed if someone couldn’t explain the system in its current state I would have zero confidence they could successfully simplify it.

	▲	zahlman 3 hours ago \| parent [-]
		My point was that the attitude of being able to explain systems by drawing them, leads to over-architecting them. If you stick to prose then you can't as easily delude yourself about the complexity by staring at pretty pictures. I was not considering the case of documenting already existing systems, just talking about the planning stage. Your point is well taken.

▲

stronglikedan 4 hours ago | parent | prev [-]

Some stakeholders will gain more understanding from a diagram than any amount of simplified prose, so both are typically helpful.