Friction That Is Not Latency

Not all friction is waiting. Some of it is a fast tool that is unpleasant to use, and no timing telemetry will find it.

The categories

Error messages that do not say what to do. A stack trace where a sentence would serve.

Multi-step commands. Four things to run in order, in the right directory, with the right flags.

Memorised incantations. A command nobody can reconstruct without finding it in a chat log.

Silent failure. Something did not work and reported success.

Inconsistency between contexts. The command differs locally and in CI, so knowledge does not transfer.

Documentation that is wrong, which is worse than absent because it costs time before it fails.

Why telemetry misses it

None of it has a duration. A confusing error message takes zero seconds to produce and twenty minutes to act on.

The time it costs is spent elsewhere — searching, asking, reading source.

It shows up in surveys and in conversation, and nowhere else. Which is the argument for asking people, made concretely.

Finding it

Ask. "What did you have to look up this week that you should not have had to?"

Watch someone new. The points where they stop and ask are the friction, and they are invisible to anyone who already knows.

Read the team chat for repeated questions. The same question asked five times is a documentation or a tooling defect.

Look at what people have aliased. A shell alias is a workaround for something the tool should have done.

Fixing it

Error messages should say what happened and what to do. This is the highest-return improvement available in any internal tool and it is almost always deferred.

One command. If the workflow is four steps, make it one that does four things.

Sensible defaults, so the common case needs no flags.

Same command everywhere. What runs in CI should be runnable locally, identically.

Fail loudly. Silent success on failure is the worst possible behaviour and it is surprisingly common in shell-based tooling.

Documentation next to the tool, in help output, rather than in a wiki that drifts.

The messages worth rewriting

Rank by frequency, which requires knowing which errors people actually hit.

Log the error types your tooling emits. The distribution is concentrated: a handful of messages account for most occurrences.

Rewrite those first. Each rewrite is minutes and pays every time someone hits it.

Include the fix in the message. "Run X to regenerate this" saves the search entirely.

Why it is worth the attention

It is cheap. An error message is a line of code.

It compounds. Every person who hits it, every time.

It is what people remember. A toolchain judged unpleasant is usually not slow — it is confusing, and the two get conflated in every conversation about developer experience.

And it is the part no dashboard will ever show you, which is why the survey and the conversation are not optional extras to the measurement programme.

Ranking error messages

Rewriting error messages is high-return and needs a ranking, because there are hundreds.

Log which error types your tooling emits, with counts.

The distribution is concentrated: a handful account for most occurrences.

Rewrite those, in order.

Each rewrite is minutes and pays every time anyone hits it.

Include the fix in the message, which removes the search entirely and is the difference between a message that informs and one that only reports.

Watching someone new

The cheapest way to find friction that is invisible to everyone who already knows.

Sit with a new joiner for an hour, without helping.

Note every point where they stop, search, or ask.

Do not explain, which is the hard part and the whole value.

Each stop is a defect in documentation, error messages or defaults.

An hour produces a longer and better list than any survey, because it captures the things people stop noticing within a month of joining.