• Ravone Arts
  • Posts
  • Diagnostics Are UX — Designing Developer-Friendly Error Systems

Diagnostics Are UX — Designing Developer-Friendly Error Systems

Why Error Messages Deserve More Attention

Author

Ramesh Ravone
August 11, 2025

Hello

If you have ever been in the middle of writing code and an error message appeared — one that left you unsure what actually went wrong — you know how quickly frustration can build. I have been there too.

That is why, when I work on developer tools, I see diagnostics not just as a technical feature but as a part of the user’s experience. An error message can be the moment where a tool either guides you forward or leaves you lost.

Why I Started Thinking Differently About Diagnostics

he best error is the one you never see. The second best is the one that tells you clearly what happened and how to fix it.

I wanted my tools to do more than point out problems. I wanted them to be like a careful colleague — the kind who notices all the issues in your code and then explains each one in a way you can act on immediately.

That thinking led me to design a DiagnosticEngine that collects all the problems it finds in one pass. This way, instead of stopping at the first issue, it shows the full set. You get a clearer picture, and you can fix things in one go.

A Few Lessons I Learned Along the Way

  1. Show everything, not just the first issue
    When all the problems are visible together, you save time and avoid the “fix-run-fix-run” cycle.

  2. Recover and keep going
    Even if the tool encounters something unexpected, it should skip past it and continue. That way, the rest of the analysis is still useful to you.

  3. Use words that explain
    Instead of simply saying: Type mismatch
    Say:
     Cannot assign value of type "String" to variable of type "Int"
     he second example helps you take action immediately.

  4. Maintain your diagnostics like any other feature
    I write tests for them, so they remain accurate and useful as the code evolves.

Quick Summary

Principle

Why It Helps

Centralized DiagnosticEngine

Keeps messages consistent and manageable

All errors in one go

Saves time and gives a full picture

Clear, specific wording

Reduces confusion

Testing diagnostics

Prevents regressions and keeps them reliable

In Closing

Diagnostics are not only about detecting mistakes. They are an opportunity to guide, to teach, and to help the person on the other side of the screen. When they are clear, complete, and thoughtfully presented, they make the entire development process smoother.

Your Turn — Join the Conversation

  1. Read the full article — it includes more examples and details.

  2. Write to me — I would like to hear about the most helpful or most confusing error messages you have seen.

  3. Share this with someone who is working on developer tools or enjoys improving the developer experience.

  4. If you design tools yourself, I would be glad to hear how you handle diagnostics.

— Ramesh Ravone