Internal jargon is not an error explanation
Aliases: internal jargon · exception class · stack trace in UI
What it is
Sentences shown to someone in recovery should not contain service names, exception classes, stacks, status phrases, or team slang. Those words are for people who already have a code table. Keeping jargon out is so the next step can be chosen in task vocabulary. It is not a ban on a copyable identifier for support. An identifier is a handle. Jargon is tone that blocks recovery.
Why it happens
Internal words force a translation pass: ECONNRESET, idempotency_key conflict, 403 Forbidden classify the event for an engineer and are noise for everyone else. When translation fails, people grab the one recognizable token and guess—timeout means retry, permission means the account is broken. Jargon also leaks architecture, putting structure that belongs in diagnostics on the primary surface. Task language states the same event as “the server could not be reached; no order was created,” and the recovery branch is immediately visible. Jargon is not professionalism. It sets the audience to a different role.
Studying it
Present the same fault as raw exception text, an HTTP phrase, or object-level task language, and let non-engineers choose a next step.
Independent variables: whether primary copy contains internal identifiers, whether a copyable reference is attached separately, whether the reader has a technical background. Dependent variables: accuracy of the recovery branch chosen, rate of treating jargon as a causal explanation, willingness to continue, attempts to follow a stack as operating instructions.
Use real product users as the main sample, not developers. A developer group can be tested separately: they too get interrupted by a stack in the main flow, just differently.
Where it stops holding
Developer tools, CLIs, and authenticated operations consoles may put jargon in the main view, but still must not print secrets, paths, or cross-tenant data. Products with mixed roles default to task language, with jargon behind an explicit “technical details” disclosure. Proper names that are already part of the user’s task (invoice, SKU) are not internal jargon; internal jargon is an implementation name that does not exist in the task.
Applying it
- Ban service names, exception classes, stacks, and untranslated status phrases from the primary surface; replace them with object, action, and state.
- When support needs to join events, use an identifier with no business meaning rather than pasting an exception string into the title.
- Scan toasts, mail, status pages, and fallback pages on the render path for unmapped internal messages.
- Verify by handing a screenshot to someone who has not read the architecture and circling every word they do not understand. Any circled word that blocks “what do I do next” comes off the primary surface.