Comment by kzhen | Hacker News Reader

Comment by kzhen | Hacker News Reader

Parent Full thread

Hi taeric, author of the article here

> 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.

Reply on news.ycombinator.com