“Developer experience” has become one of those terms that means everything and nothing. Every tool claims to prioritize it. Most of them are lying — not maliciously, but because they haven’t thought carefully about what it actually means.
Here’s my working definition after years of building tools and APIs that other developers use: Good DX means minimizing the distance between intent and outcome.
That’s it. Everything else is a corollary.
The three failure modes
Most bad DX falls into one of three buckets:
1. The right path isn’t obvious. You can do the thing, but you have to read docs, try things, fail, search Stack Overflow, and eventually stumble into the right answer. The API surface is flat — everything looks equally important, so nothing is.
2. The wrong path is too easy. You can shoot yourself in the foot without much effort. SQL injection through string interpolation. Race conditions through shared mutable state. Security vulnerabilities through permissive defaults. Good DX makes the unsafe path at least inconvenient.
3. Error states aren’t recoverable. The worst thing a tool can do is put you in a state you can’t reason about. Unclear error messages, corrupted local state, silent failures — all of these force you out of flow and into forensics.
Designing for the error case first
Here’s a practice I’ve found useful: design your error messages before you design your API.
If you can’t write a clear, actionable error message for a given failure state, it’s a sign your API is underspecified. The act of writing “If X happens, tell the user: …” forces you to confront the ambiguities in your mental model before they become bugs in your code.
The best error messages have three parts:
- What went wrong — specific, not generic
- Why it went wrong — the actual cause, not a symptom
- What to do about it — a concrete next step
Error: ENOENT: no such file or directory is not a good error message. Cannot find 'src/index.ts' — make sure the file exists and your tsconfig.json rootDir is set correctly is.
The progressive disclosure principle
Good API design is layered. The first layer handles 80% of use cases with minimal surface area. Deeper layers expose more power for users who need it, but they’re opt-in — they don’t contaminate the simple path.
React’s hooks are a decent example. You can build most of what you need with useState and useEffect. The more powerful hooks — useReducer, useContext, useMemo — exist for when you need them, but you’re not confronted with them until you are.
The failure mode here is exposing too much surface area too early. When every option is front-and-center in the docs, beginners don’t know what to ignore. They optimize prematurely, reach for complexity they don’t need, and end up with code that’s harder to reason about.
Consistency is underrated
One of the most consistently underrated aspects of DX is consistency. If similar things behave similarly, you can build a mental model and apply it across the system. Every inconsistency is a tax on that model.
This is why API design conventions matter so much. REST naming conventions, GraphQL type naming patterns, CLI flag consistency — these aren’t aesthetic preferences. They’re cognitive offloading. When everything follows the same rules, you don’t have to remember each thing individually.
Empathy is the actual skill
Everything above is really just applied empathy. You have to genuinely care about the experience of the person using your tool — not as a user persona, but as a specific person at a specific moment, trying to do a specific thing and probably a little frustrated.
The engineers who build the best DX are usually the ones who are still close enough to the beginner experience to remember what it felt like to not know things. Expertise is great, but it can make you blind to where the sharp edges are.
I write about tooling, API design, and software craft. Subscribe if any of this resonates.