> 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)
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.
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.
Now, story boarding a communication sequence between systems can make great use of layout. So, I definitely see potential.
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.
[1] https://abbycovert.com/stuck/ [2] https://www.learnupon.com/blog/multimodal-learning/
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.