Forem: Cesar Garza

Diagrams as Code Just Make Sense

Cesar Garza — Tue, 25 Nov 2025 16:10:51 +0000

When I was in college, one of my software engineering class obsessed over UML diagrams. Creating them was painful, especially with the clunky tools available in the late 00s, and it felt like an exercise in frustration more than anything useful.

So when I entered the real world and discovered that most teams didn’t make diagrams regularly, I was honestly relieved. But over the years, I realized something: diagrams are incredibly valuable, we just never had tools that made them worth the effort.

My last team relied on diagrams for planning, communicating with non-technical stakeholders, and even thinking through refactors. But the visual tools we used were still slow, fiddly, and frustrating. (Looking at you, arrows that refuse to anchor to properly.)

Then someone introduced the team to Mermaid,, and everything changed.

This post gives a quick rundown of what Mermaid is, how we used it, and why you should consider adding it to your engineering toolkit. (Not sponsored — just a fan.)

Why Diagrams Actually Matter

Even if many teams skip diagramming, the benefits are huge:

Discover architectural gaps early.
Visual representation of the system helps technical and non-technical teammates understand intention.
Easily surfaces dependencies.
Creates referenceable documentation, decreasing the reliance on tribal knowledge

The real issue isn’t that diagrams aren’t useful, it’s that diagramming has historically been slow and miserable. And in my opinion, Mermaid fixes that

Introduction to Mermaid

Per Mermaid:

Mermaid lets you create diagrams and visualizations using text and code.
It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

Sure, they offer a traditional visual editor (and even an AI diagramming tool now), but the real power is in the “diagrams-as-code” approach.

A simple class diagram looks like this:

---
title: "Animal example"
---
classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

and becomes:

The syntax is easy to pick up, expressive enough for complex diagrams, and supported by many tools developers already use like GitHub and Notion.

Where Mermaid Shined for My Team

1. Technical Planning & Architectural Thinking

One of our junior engineers kept rushing into implementation, which led to rework during code reviews. When we gave them a feature track to lead as part of their career development efforts, we also asked them to write a tech spec, including class diagrams and sequence diagrams, ahead of the rest of the team coming onto the track.

They used Mermaid for everything.

The result?

A living, frequently referenced document that evolved along with the project. It clarified dependencies, surfaced edge cases, and gave the whole team shared context.

Mermaid made that possible because diagrams were fast to write and easy to update.

2. Living Documentation (Instead of Stale Images)

Traditional diagrams rot quickly.

With Mermaid, the “source of truth” isn’t a PNG — it’s the code that generates the diagram. Easy to update, diffable, and version-controlled.

We started keeping diagrams within the rest of our Notion documents and RFC PRs. They were updated as the system evolved. For once, diagrams didn’t feel like artifacts from a previous era, they felt alive and you knew how to modify them.

3. Clear Communication With Non-Technical Stakeholders

I was once asked to create diagrams explaining:

Where data lived
What systems existed around the monolith and the microservice
The flow of operations end-to-end

With Mermaid, I quickly built:

An architecture diagram
A mind map
A sequence diagram

These weren’t one-off illustrations, they evolved as discussions progressed. We even used them when onboarding a new PM to show pain points introduced by the microservice.

The feedback was overwhelmingly positive. Mermaid diagrams made complex systems legible.

Closing Thoughts

Mermaid removed all the friction that used to make diagramming feel like a chore. Suddenly diagrams were fast to create, easy to maintain, and actually fun. Our team saw a noticeable adoption spike once engineers realized how powerful and lightweight the tool was.

Developers often rush to implementation or skip documentation because visual tools slow them down. Mermaid flips that dynamic — it makes diagramming feel like writing code: quick, iterative, versionable.

If you’ve avoided diagrams because the tooling was awful… give Mermaid a try. It might change the way you design systems.

Are you already a Mermaid user? Thinking of trying it out? I’d love to hear your experience.

If you want to read more from me, check out my Being A Great Developer Is More Than Just Code Output series:

Being A Great Developer Is More Than Just Code Output - Mentorship

Cesar Garza — Tue, 28 Oct 2025 17:03:53 +0000

When I chose Computer Science as my degree, I had three reasons — and it turns out I was wrong about two of them.

I thought it would lead me to game development.
All the alternative job options sounded like something I’d enjoy doing.
Most importantly, I believed I wouldn’t have to deal with people much.

I’m definitely not a game developer, but I was very wrong about that last one. What takes you beyond senior developer isn’t your code output, it’s your social skills and your ability to help others grow.

This post is the third entry in my series Being a Great Developer Is More Than Just Code Output. You can find the previous posts here:

Finding Passion for Mentorship

I’ve been developing software for about 15 years now, across different teams, companies, and setups. But my first job opportunity — as an intern — marked me the most.

It was a small, 10-person team. Everyone was a few years older than me, yet they were kind, patient, and genuinely eager to teach. I looked up to one engineer in particular — a natural mentor who helped me find my footing. His generosity with his time and knowledge had a huge impact on me, and that experience has stayed with me ever since.

Most of my career has been at smaller teams, which meant there was little to no room for junior engineers, and career development wasn’t a top priority. I left many of these jobs because I felt like I had learned everything I could and started to feel stagnant.

At my last company, that opportunity finally became formalized. The team had a mix of early-career developers, many just out of college or bootcamps, alongside senior engineers. That setup immediately caught my attention — it was a space where mentorship could happen.

By joining the Career Development Committee, I helped refine the engineering growth framework to clarify what was expected at each level and what was needed for promotion. That led me to later co-lead the coaching program, which put me — and other senior engineers — in a position to help our junior peers level up. It was incredibly fulfilling, not just for the impact it had, but for how it rekindled something I’d been missing: a passion for mentorship and the desire to pay it forward.

Why Mentorship Matters

So why should senior developers care about mentoring? Why should you make space for it, formal or not, when it doesn’t directly ship features or move metrics?

Mentorship strengthens your team’s culture, fosters collaboration, builds trust, and scales knowledge. The time you invest in helping others grow comes back through faster PR cycles, tighter feedback loops, and higher-quality output. It turns a collection of individuals into a cohesive, resilient team.

For you personally, mentorship is how you grow from being a great coder to being a great developer. It teaches you to:

Break down complex ideas clearly.
Develop empathy and patience.
Recognize potential in others.
Give effective, constructive feedback.
Flex your leadership muscles — with or without the title.

A team where everyone — regardless of seniority — is constantly learning naturally stays longer. I’ve seen retention stretch from the usual 2–3 years to 5+ when mentorship is part of the culture.

Although it can happen, where the best technical engineers get promoted to leadership positions — either on the management or technical track — in my opinion, the ones that should be in those positions are those who lift others up.

Mentorship in the Age of AI

Now, let’s talk about the elephant in the room: AI.

We’re in an era where many teams are cutting junior roles in favor of AI tools. I’ve heard comments like, “This AI can do what a junior dev would take three times as long to do.”

Sure. But the AI agent doesn’t learn between sessions. It doesn’t gain context. It doesn’t mentor others.

If you stop hiring and growing junior engineers, you’re jeopardizing your team’s future. You lose the next generation of talent, institutional knowledge, and diverse perspective.

That’s why, as senior developers, we should advocate for mentorship and early-career hiring. Even if it takes time and effort, it’s a net positive for everyone and for the industry.

Here’s why it matters:

Continuity: Seniors move on. Juniors carry forward the team’s context.
Resilience: AI still needs human judgment. You need devs who can use it wisely.
Sustainability: Mentorship builds a healthy, diverse, long-term talent pipeline.

Mentorship isn’t just “nice to have.” It’s an act of stewardship — for your craft, your team, and your industry.

Mentorship vs. Coaching

In my last role, the company leaned more heavily on coaching than mentorship. The two overlap, but they serve different purposes.

Coaching is focused and time-bound — goal-oriented, structured, and measurable.
Mentorship is broader and relational — rooted in trust, curiosity, and growth.

Personally, I always leaned toward mentorship. My goal wasn’t just to help someone fix a bug or hit a short-term milestone — it was to help them develop their voice as an engineer.

The most meaningful part of mentoring was the relationships that lasted beyond the formal engagement: the check-ins, the technical chats, the career talks. The feeling that someone could always reach out for guidance or advice.

That’s the kind of connection that shaped my own career and it’s the kind of mentor I strive to be.

Closing Thoughts

Mentorship is how we turn knowledge into legacy.

Being a great developer isn’t just about solving hard problems — it’s about helping others solve them, too. It’s about sharing your context, your empathy, and your experience so the next generation doesn’t have to start from zero.

If you’re a senior developer, mentor someone. If you’re in a position to influence hiring, advocate for junior engineers. And if your company doesn’t have a mentorship program — start one.

Because what takes you beyond senior isn’t your code — it’s your impact on people.

Being A Great Developer Is More Than Just Code Output - Collaboration — Non-Devs roles in your team matter as much

Cesar Garza — Wed, 15 Oct 2025 16:26:12 +0000

Developers are known to have an ego, be rude, anti-social, or lack people skills. They often think themselves smart because they can code. Personally, I’ve always believed that anyone can code; being a good developer is more about knowing how to use a search engine and ask the right questions.

This might be changing a bit in the age of AI-assisted coding, but the point remains: developers aren’t smart just because they know how to code. The sooner a dev acknowledges that non-technical teammates are also intelligent and deserving of respect, the further they’ll go in their career.

The focus of this post is on the non-technical roles developers interact with most often — QA, Product Managers, and Designers.

This is the second post in my series Being A Great Developer Is More Than Just Code Output. You can find the first post about Code Reviews here.

Let Go Of Your Ego

Part of the job of QAs, PMs, and Designers is to review your work: checking for bugs, verifying requirements, and ensuring that designs match expectations. Just like with receiving code reviews, you are not your code. You’re human. You’ll make mistakes, overlook details, and that’s okay.

Making mistakes doesn’t make you a bad developer. These roles exist to support you so that issues don’t reach production and affect customers. It’s not you vs. them, you’re on the same team, working toward the same goal.

I’ve often seen this ego-driven defensiveness, especially from junior developers (my younger self included). It’s a natural reaction to feel protective of your work when it’s being “criticized.” But reframing that feedback as collaboration — not confrontation — changes everything.

QA is your friend. They’re probably overworked and underpaid. Be kind.

Give Respect To Earn Respect

I’m a firm believer that no one is owed respect for their title or position; respect is earned through how you treat others. As a developer, you have to show up and give respect to non-coding teammates.

I’ve been in many rooms, both virtual and in-person, where people dismiss the work of QA, PMs, or Designers. That kind of attitude poisons collaboration. Each person brings expertise in their field just like you do in yours. Ego is the enemy of effective communication.

Once you let go of your ego, it becomes much easier to recognize and respect the knowledge others bring to the table.

Bring Everyone Along

In my previous post, I talked about how giving code reviews kindly and thoughtfully can help others learn and “pay dividends” over time. The same idea applies here.

Building a strong relationship with non-technical teammates by communicating openly, explaining clearly, and listening respectfully, benefits everyone in the long run.

Let’s focus on relationships with Product Managers as an example.

Throughout my career, I’ve seen two extremes:

The dismissive dev, who’s short and overly technical, uses jargon to avoid explaining things. This creates distrust, leads to overpromising, bad requirements, and a lot of wasted time.
The over-explainer, often a senior developer, who dives too deep into implementation details and loses the PM’s engagement. Even with good intentions, it can overwhelm the conversation or slow decision-making.

The sweet spot is finding the right level of technical depth. Explain enough so they understand the trade-offs and constraints, but skip unnecessary intricacies.

For example, our team once walked a PM through how a new microservice integrated with our monolith, we avoided buzzwords like “JWT tokens” and instead focused on how data flowed between systems. That session gave the PM enough context to write better stories, plan more accurate timelines, and help the team divide work efficiently.

As a developer, keeping a mindset of teaching and including others, no matter their background, builds trust, understanding, and efficiency over time.

Be A Leader, Regardless of Seniority

You don’t need a formal title to act like a leader. Leadership starts with how you treat people and how you help them grow.

Treating others with respect, bringing them along, and letting go of your ego are all key leadership traits. Another piece of that puzzle is fostering unity within the team — companionship instead of division.

Put these principles into practice, and you’ll naturally become someone others look to for guidance.

Closing Thoughts

A great engineer doesn’t shine by writing flawless code, but by how they collaborate with others, especially with non-technical teammates.

A healthy, respectful team dynamic not only leads to better results, it makes the day-to-day far more enjoyable. As developers, it’s on us to help foster that kind of environment, one where everyone feels heard, valued, and supported.

If this post resonated with you, or made you reflect on your own team dynamics, I’d love to hear your thoughts. How do you approach collaboration with non-dev roles? What’s worked (or not) for your team?

Next up in the series: “Being a great developer is more than just code output — Mentorship.”

Being A Great Developer Is More Than Just Code Output - Code Reviews

Cesar Garza — Tue, 07 Oct 2025 16:04:27 +0000

As developers, we obsess over writing clean, tested, performant code; and rightly so! But being a great developer goes far beyond your own output.

When I started my CS degree, I thought software engineering was about working with computers, not people. I couldn’t have been more wrong.

This is the first article in my 'Being a Great Developer Is More Than Just Code Output" series, aimed at mid-level and senior engineers looking to grow the skills that make teams thrive. Today’s topic: Code Reviews.

👨‍💻 Giving Great Code Reviews

Assume Positive Intent

Start from a place of respect and curiosity. The person wrote this code trying to solve a problem, not to make your life harder. Ask questions like "Can you walk me through why you chose this approach?" to foster collaboration. Using statements like "This is wrong" shut it down.
Review the Code, Not the Coder

Give objective and specific feedback about the code itself. Reviews like "This method is too long", "The class can be broken down, it's doing too much; I recommend this approach ...". Avoid pointing fingers at the Engineer with things like: "You made a mess in this class, I can barely understand it. Fix it and let me know when it's easier to review", "Do you even know how to write performant code?".

Use this as an opportunity to lift others up, a simple "Great idea!" can release some tension from other critical code.
Prioritize Signal Over Noise

Spend your time commenting on things that affect correctness, readability, or long-term maintainability first, not whether they are following your same coding style/guideline (if not enforced... for example, Ruby's symbols vs rocket notation. Rely on linters if you feel it's important.
Explain Why, Not Just What

A good leader uses code reviews as an opportunity to teach. It might take more time, but it'll be a force multiplier in the long run. Providing feedback like: "Use map instead of each" will lead the developer to just change the method without fully understanding the preference, they might even think you are being nit-picky.

I found a lot of success providing direct links to the Ruby/Rails docs of the method I was suggesting using; "I recommend using map (link to docs)". With this, I was accomplishing three things:
- Direct them to the docs familiarizes the developer with them more, makes them rely on these tools more often.
- "Saves me time" noting down the explanation/justification, the docs already say what the method does. It allows the developer to connect the dots, or ask for more details if needed.
- Leaves a better "paper trail" in the PRs of the changes and reasons for those changes that people can reference.
Balance Gatekeeping With Empowerment

Be a safety net, not a roadblock. If the code is safe and can evolve, merge it. Perfectionism kills velocity. A review that leaves the author feeling confident and trusted is more valuable than one that’s "technically perfect."
Pair Review The Code

Pairing can transform reviews. It saves time deciphering intent and helps both sides explain their reasoning in real time. It’s also a great chance to collaborate on changes directly.

🧩 Receiving Code Reviews Gracefully

You Are NOT Your Code

Getting something you spent a lot of time and thought on getting critically reviewed isn't a measure of how good a developer you are. Look at this as a learning opportunity to receive feedback from someone more experienced.
Seek Understanding Before Defending

When you might not agree with comment, ask for clarification rather than justifying your decision and dismissing it. Often, confusion in review means future readers will be confused too. Maybe it can be a learning opportunity for both.
Clarify Your Intent in Context

Don't be afraid of providing comments within the PR before submitting for review explaining what certain things do to make it easier on the reviewer. Note that if you are having to explain several things that seem "obtuse", it might be a sign your code needs refactoring.
Recognize Patterns in Feedback

If you see the same comment more than once (naming, testing, structure), document it in your personal checklist or team guidelines. That’s how you level up systematically.

Using Code Reviews As a Learning Tool

One of the things I struggled with was getting more Jr devs to do Code Reviews, since they were often working with way more senior developers. So they'd either just approve because "the senior knows better than me" or they'd feel they have nothing to offer.

But once I encouraged them to use Code Reviews as a learning tool, go into their senior's PRs and ask questions, ask why they took a certain approach, or why they preferred a certain method, they actually started doing it, growing and losing some of that imposter syndrome that they didn't have anything to offer. Soon they'd be catching typos, or making some smart suggestions.

Closing Thoughts.

A great engineer doesn’t shine by writing flawless code, but by helping others do the same.

The best codebases grow when people do. And that starts with reviews grounded in respect, curiosity, and a desire to raise everyone’s game.

Next up in the series: “Collaboration — Non-Devs roles in your team matter as much.”

As I mentioned, I planned on making this a series Being a great developer is more than just code output, coming soon I'll be talking about Collaboration
Is there something important you think I missed?