Architecture diagrams enable better conversations

I find architecture diagrams particularly useful for interviews of high-level candidates. I'll structure the first half as an informal conversation where I pick up some technical work they've done and get them to talk about it in depth.

The second half is usually explaining the 10kft and 1kft arhitectural overview of our product. However, I find that pre-prepared architecture diagrams are not that helpful in this case. I just open up an excalidraw tab, screen share, and sketch out the diagram in real-time, explaining things as I go along, and trying to elicit conversation about the design.

I do this because my biggest challenge when tackling new work is not necessarily the code, but the context of it. Where does this live? Where does it receive its inputs from? Where dose its outputs go? How are all of these things organized into the bigger picture? What gets persisted? What's transient?

A good grasp of overall architecture allows you to produce your own heuristic for how to navigate the code, where to look for problems, build internal models of where things might be going wrong, etc.

The sketches get thrown away each time. The process of drawing it out and explaining it is the value.

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've worked with documentation auto-generators before, and the problem they have is that they can't figure out which references are relevant and which aren't. I remember auto-generating a class diagram of a Java project in the late 90's and it showed every class having a reference to the class "java.lang.String". Generators have gotten (a little) smarter with one-off heuristics like "treat the class String as if it were a primitive", but they're still way more cluttered than a knowledgeable human would ever come up with.

You're going to get a lot of advice, but some general comments for your consideration. As always, your mileage may vary.

> failed a number of technical interviews because I can't make architecture diagrams

I would caution against correlating interview failure to a lack of diagramming skill. Diagramming is a teachable skill; how to formulate architecture is much more complicated. If I am considering hiring someone who I see can design strong architectures but couldn't represent that in a diagram, I'm probably not dismissing them because of their drawing skills. But that's only when I believe they can design an intended architecture.

> I can't for the life of me draw the architecture of anything

I had an engineer on one of my teams who had the same problem. With him, he understood some things but in other aspects he was more murky. So, I asked him to start by writing down the architecture. Literally, write words and sentences that describe the collective of systems, i.e. Service "A" is a REST API, and it connects to Database "B"; a client connects to Service "A" over HTTPS, etc. etc. I don't know if this would help, but if you can do that, you can start to translate the words to pictures.

> I don't know how people learn to do that

By doing. I don't know anyone who has ever been trained to create an architecture diagram that knew what they were talking about. Just start small, and then ask someone to describe it back to you. When you begin to hear what you consider to be correct, you'll know you're making progress.

> I've never used diagrams in my day-to-day work

This tells me a couple of potential things: you're possibly not working in complex or large systems, or maybe are not responsible for communicating those systems to others. "Complex" is a relative term, so interpret that as you may. Ultimately, arch diagrams serve as a way to visualize complexity with the goal of letting others understand.

Also, in order for them to capture appropriate granularities of detail, they take a lot of time and conversation with readers.

I usually go with as little graphs as possible and prefer to write text; it can capture more, better, faster, and be more iterable. For specific areas like state machines or packet sequences I will drill into graphical representations more but otherwise... eh. Text wins.