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.

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.

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.

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

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.

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.

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

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.