I'd love to see some examples. I know that the article mentions this as a downside of C4 diagrams, so consider this a plea to action from folks. I'd love to see examples of how these help.
On the onboarding story, I'm specifically curious how/why diagrams work more than a bulleted list and other conventions could already do? What are the entry points? Is there a convention on how entry points are named? If not, why not?
I love the idea of having a diagram that works as a reflection of the codebase. Hard not to think of ways that can help. I'm always worried that too much effort goes into the reflection, though. Especially when it is front loaded in the effort.
> On the onboarding story, I'm specifically curious how/why diagrams work more than a bulleted list
the point I was trying to make in the article was that having a visual representation helps new developers to build up a mental model of the different components of a software system. In my particular case the system in question is made up of: 2xAPI, 2xEvent Processors, Event Producer as well as dependencies on external systems. The architecture diagrams are helpful here as the new developers are able to see the interactions between components.
> I love the idea of having a diagram that works as a reflection of the codebase.
In C4 there are 4 levels, the first is the system view this doesn't bear much resemblance to the codebase, the second is the container level, this is where you show the different components that make up a system. It's important to note here that a component is a deployable "thing", e.g. an API, database, powershell/bash script etc. This is where you start to see a bit more of a link between the architecture diagrams and the codebase. My experience of level 3 and level 4 where you start to model the actual codebase didn't bear much fruit and there are tools which can do a good enough job here from scanning the code (particularly in the dotnet world, NDepend does a brilliant job, although £££s)
I didn't say it directly, but thanks for the article!
My question is probably more asking exactly how/why the visual representation helps. I am very open to the idea that they do. But I'm also open to the idea that it is the active interaction with others that is the important part. That it is done with text or with drawings feels secondary. Almost distantly.
Your point about the really high level views of 1 and 2 in the levels feels notable. I also really resonate with the idea of identifying the deployable "things" that can be independently reasoned about. If you have a team that is pushing libraries between the two things, you then have to expand this discussion to the build and deploy systems as being integral to your team, not merely secondary considerations.
I believe that the way we represent information is key to understanding. Data points in a list are usually way less insightful than a good graph (emphasis on good).
What I have found is that it's the case in describing system architecture as well.
As you say, you can describe a system in a few paragraphs, explaining the relationship between the main components. However, as paragraphs it can harder to grok, and also harder to write with no ambiguity.
Now, part of what I say above can be seen as personal preference (text vs image), but in practice I have found that when using tools like plantuml or mermaid to make C4 diagrams, the result is easier to use, remember, and update than plaintext.
I think I mostly just disagree, here. I want a graphical representation to be more impactful. But typically any system that scales such that a short list can't explain entry points and dependencies has scaled beyond what graphical tools can do, as well.
Now, story boarding a communication sequence between systems can make great use of layout. So, I definitely see potential.
I believe that one of the big things that diagrams help with is maintaining state while having a conversation. You don't have to keep track of so many things in your head and it works in a similar way to the "tell ’em what you’re gonna tell ’em, tell ’em, and then tell ’em what you’ve told ’em" style of presenting--your audience gets to see up front what journey you are taking them on.
There's a great book by Abby Covert about diagrams in general: "Stuck? Diagrams help."[1]
From a learning perspective, having multimodal[2] options, such as a mix of visual (diagrams), reading, and videos/audio can really help with onboarding. Different people learn better with different methods, and different methods work better in different contexts, for example I personally hate sitting at my desk watching a video, but enjoy doing so on my phone while commuting.
Definitely agreed. I have found diagrams, and tools that let me edit them quickly, to be great "state trackers" in design and planning meetings. You can get consensus, keep track of the decisions that were made, and then have a shared model you can use to coordinate building that plan.
This has value even if the diagram is immediately obsolete and discarded once the project is complete.
On the onboarding story, I'm specifically curious how/why diagrams work more than a bulleted list and other conventions could already do? What are the entry points? Is there a convention on how entry points are named? If not, why not?
I love the idea of having a diagram that works as a reflection of the codebase. Hard not to think of ways that can help. I'm always worried that too much effort goes into the reflection, though. Especially when it is front loaded in the effort.