4 ms·

> That said, you probably don’t want to be making theoretical architecture diagrams most of the time. My take on this is that it's really hard to have one diag

> That said, you probably don’t want to be making theoretical architecture diagrams most of the time. My take on this is that it's really hard to have one diagram to rule them all. I think there's a time and a place for different kinds of diagrams, and I think it's ok to tell a story with a couple different ones. For example, a conceptual diagram that complements the actual "as implemented" diagram. One is a big of a "here's what we were thinking" and the other is "here's how we translated that to actual architecture". In my role of frequently having to manage up to executive management, investors, onboard new people, etc. the combination of conceptual plus actual is powerful. I can describe the problem we're solving, provide a grokkable format for most levels of the org chart, and then have the details for those who want to dig in to discuss how we built (or plan to build) it and why.

datadrivenangel 2y ago
And then you have the diagram evolution cycle: Step 1: People want a simple high level architecture diagram. Step 2: People want more detail Step 3: People want to see how human components of the system work Step 4: The diagram is so complicated and non-obvious that people start asking for a simpler high level architecture diagram. The only way to escape is to be clever about preserving multiple 'zoom' /C4 levels of diagram.
- fatnoah 2y ago
  > The only way to escape is to be clever about preserving multiple 'zoom' /C4 levels of diagram. Fully agree. Having gone through startup funding rounds and acquisitions, that's the set of diagrams that I have ready or prepare for each one. The "suits" like the higher level stuff, while the people digging into technical due diligence or post-acquistion integration like the more detailed ones. They're also adaptable at many levels for any domain-specific "enhancements" that are necessary, such as a data flows, security flows, and the like.
billyp-rva 2y ago
> For example, a conceptual diagram that complements the actual "as implemented" diagram. One is a big of a "here's what we were thinking" and the other is "here's how we translated that to actual architecture". It maybe could have been clearer in the article, but the intent wasn't to discourage "here's what we were thinking"-style whiteboard diagrams. Those absolutely have their place. The article is trying to discourage people from making "here is how Kubernetes works" or "here is how microservices work" diagrams, since you can easily find those online.
seanc 2y ago
Exactly! Several different sorts of folks have an interest in product architecture, and each group needs the story told at a different level of abstraction. So inevitably one has to maintain a few different flavours of the diagram and associated story. One way I think of it is that the architect needs to market the architecture, at least a little bit. If you ask a marketing team to deliver a message they immediately start crafting multiple delivery methods to meet people where they are at. Architects shouldn't think they can somehow escape that basic requirement of effective communication.
parpfish 2y ago
I often think of Marr's "three levels of analysis" from cognitive neuroscience when thinking about technical communication and different audiences. there's the "computational level" (poorly-named, focused on high-level objectives of the system), algorithmic level, and implementational level. works for understanding any information processing system, not just brains/minds as he originally planned
lanstin 2y ago
Code architecture, component architecture, physical architecture as fully deployed. Data architecture. The design of adding ljkely new features. So many things to decide and communicate. So many presentations with at best one thing explained.

datadrivenangel 2y ago

And then you have the diagram evolution cycle: Step 1: People want a simple high level architecture diagram. Step 2: People want more detail Step 3: People want to see how human components of the system work Step 4: The diagram is so complicated and non-obvious that people start asking for a simpler high level architecture diagram. The only way to escape is to be clever about preserving multiple 'zoom' /C4 levels of diagram.

fatnoah 2y ago
> The only way to escape is to be clever about preserving multiple 'zoom' /C4 levels of diagram. Fully agree. Having gone through startup funding rounds and acquisitions, that's the set of diagrams that I have ready or prepare for each one. The "suits" like the higher level stuff, while the people digging into technical due diligence or post-acquistion integration like the more detailed ones. They're also adaptable at many levels for any domain-specific "enhancements" that are necessary, such as a data flows, security flows, and the like.

billyp-rva 2y ago

> For example, a conceptual diagram that complements the actual "as implemented" diagram. One is a big of a "here's what we were thinking" and the other is "here's how we translated that to actual architecture". It maybe could have been clearer in the article, but the intent wasn't to discourage "here's what we were thinking"-style whiteboard diagrams. Those absolutely have their place. The article is trying to discourage people from making "here is how Kubernetes works" or "here is how microservices work" diagrams, since you can easily find those online.

seanc 2y ago

Exactly! Several different sorts of folks have an interest in product architecture, and each group needs the story told at a different level of abstraction. So inevitably one has to maintain a few different flavours of the diagram and associated story. One way I think of it is that the architect needs to market the architecture, at least a little bit. If you ask a marketing team to deliver a message they immediately start crafting multiple delivery methods to meet people where they are at. Architects shouldn't think they can somehow escape that basic requirement of effective communication.

parpfish 2y ago

I often think of Marr's "three levels of analysis" from cognitive neuroscience when thinking about technical communication and different audiences. there's the "computational level" (poorly-named, focused on high-level objectives of the system), algorithmic level, and implementational level. works for understanding any information processing system, not just brains/minds as he originally planned

lanstin 2y ago

Code architecture, component architecture, physical architecture as fully deployed. Data architecture. The design of adding ljkely new features. So many things to decide and communicate. So many presentations with at best one thing explained.