I think a great rule for drawing boxes-and-lines architecture diagrams is: never have overlaps or cycles. If you can't avoid one or both, it's a sign that you're providing too much detail. Zoom out to a different conceptual level, or split the diagram up.

The point of boxes-and-lines diagrams is to quickly incept your system model into the mind of someone without much context. (Maybe even yourself, after an e.g. vacation!) Choose simplicity over completeness. ASCII is often the best choice because it forces you to stay simple.

Diagrams are the on-ramp to establish a shared context, but they're most effective when combined with (simple!) prose describing components and behavior in more detail. Again, stay at a high level: readers will dig in to other docs or code if they want more detail.

An ideal README has a 1–2 sentence description of the project, and then a high level system diagram, with a couple paragraphs of explanation. The goal is to provide context for understanding the project in relation to other projects, and for understanding further docs/code.

To further stress the importance of simplicity and staying high level in communication - agilemodeling.com/essays/communi…

C4?

What's that

c4model.com by @simonbrown

//unless there’s other c4 I’m not aware of :)

c4model.com just before I left TomTom started putting it in to replace all UML etc. There are also PlantUML templates to be found in the wild... as close to a standardized ansi graphs that I can currently think of...

Interesting, haven't heard of it. I would prefer "C3" as I find UML never delivers value, but I like the basic idea

from what I understood the idea is to not insist on the deepest level, only if it does provide value to explain a complex sequence of events or some important impl detail, the highest 3 are more important

Correct; I don’t recommend level 4. And level 3 can often be too much detail too, so most teams seem to use levels 1 and 2.

I've used C4 a few times, and my favorites constraints which improve diagrams are: - it forces you to label your arrows - it forces you to keep all boxes at the same abstraction level It makes a huge difference in making the diagrams easy to grasp

Also a shame Container means something else... spitballing, I like Systems (high level, logical parts of an architecture), Processes (discrete, running artifacts implementing part or all of a system) and Components (well-defined code entity implementing part of a process)

“container” wasn’t a term widely in use when I came up with the terminology ~2011. I did consider “process”, but that breaks down quite quickly when you look at how (e.g.) multiple Java EE apps packaged as .war/.ear files can be run in a single Java process. Naming is hard. 😀

There are VS Plugins for PlantUML and C4 so you can place those diagrams next to the code

—————————— | Doubly-linked list | —————————— 😉

☝️

What about, "I feel my architectural concept is best described in a song"? (but will admit overlaps are bad)