Doing Diagrams Is Fun, Claude Helped Me Make It More Fun

Doing Diagrams is fun

Since college days, I’ve struggled with diagrams. I still remember my firsts UML or sequence diagrams, even though they were technically “ok,” I never managed to make them look presentable.

That always bothered me, because diagramming is one of the most useful things an engineer can do. Turning a written spec into a visual exposes the gaps in your thinking, and it’s often the fastest way to get others to understand your solution.

Meanwhile, I’d watch coworkers open FigJam or Miro and, in a few minutes, turn an idea we’d written on paper into a near-perfect visual. The same thing took me hours.

I have always known diagramming is really two jobs. The first is technical drafting: gathering information and scoping the architecture, its components and decisions. The second is translation: turning that draft into something visual. I’m good at the first one, and I enjoy it. The second one is where I get stuck.

Why i get stuck at it?

There are different diagrams and they describe different things, from UML and sequence diagrams to frameworks like the C4 model. I have a good understanding of what to use when, but my main problems have always been three things:

• Tools: I really like diagramming in my sketchbook, not with my trackpad. I’ve always found it tedious; at this point, I’d rather draw on my iPad lol.
• Visuals: Sizes, fonts, arrows, alignment, etc. have always been a pain for me. Even if a diagram describes what you need it to describe, if it’s visually unbalanced or ugly, it will immediately make ANYONE reject it.
• Audience: Most of the time, the audience for these diagrams is technical people, but I still want everyone on a team to be able to read an L1 System Context diagram and understand it. I think that’s a good rule to keep in mind.

Once I’d defined where my flaws were, they were easier to attack. And since my problems weren’t about understanding diagram frameworks or conventions, I think we know a guy who can help us with this :)

How I use Claude to help me with this

With Claude, I’ve developed a series of skills that help me with planning, developing and now, diagramming.

On my latest project, I’ve been feeding a Claude Project information about a new engagement we are kicking off: all my notes, plus the architectural decisions and assumptions made during the sales phase. That way, Claude had all the architectural context it needed. Now it was time for me to diagram the proposed architecture.

C4 Model: Similar to how I started this blog post, this is how the official C4 model site introduces itself.

The C4 model is basically a framework that sets clear levels of abstraction for a software system. That way, we can easily ask for a System Context diagram, a Container diagram and so on, and in the context of the C4 model, everyone knows what we are talking about.

This is what I usually use to describe what a project will look like and to propose an architecture, but now, with Claude, I had the chance to do it in an easy, clear way.

I instructed Claude to use the FigJam board I provided and, based on the documents I gave it, apply the C4 model to create the first two levels of abstraction: a System Context and a Container diagram. The results were simply fantastic.

Not only was Claude efficient and grounded thanks to the previous work I did, it also tackled my three main issues from above.

I didn’t have to start from scratch in FigJam, set sizes, or copy and paste boxes. Both diagrams were so clear that, so far, non-engineers have looked at them and clearly understood where we are going.

From there, my next step was to turn this into a skill I can re-run, which I’m sharing here as well :)

https://github.com/JesusGerardoAguiar/diagrams-skills

Hope you liked this short read, and if you feel the same way about diagrams, hopefully this small skill can help you out!

Happy Coding :)