Describing technical situations precisely

"The API is slow." "Errors are through the roof." "The code is a mess." Every one of these is a mood wearing the costume of a report. Professional technical description has a grammar of its own, and it is the same grammar whether you are describing latency, an error spike, a suspected data leak, or a smelly module: quantity, baseline, trend, scope, confidence. This chapter walks the common situations and gives you the standard wording for each.

The description formula

Every strong technical description answers five questions:

The compressed template: metric, number, versus baseline, since when, in what scope, per what source. "Checkout p99 is 340ms against a 120ms baseline, flat since the 14:00 deploy, eu-west only, per the edge dashboards." One sentence, five answers, zero adjectives. You will not always have all five; the professional move is saying which you are missing: "no baseline handy, but 340ms feels roughly triple normal."

Latency

The vocabulary that marks fluency:

• Percentiles, not averages. p50 (median), p95, p99, and tail latency (the slow end). "Average latency is fine" is a rookie tell, because averages hide the tail where users actually suffer: "p50 is untouched; the regression is all in the p99."
• Standard verbs and adjectives: latency is elevated (politely high), degraded (worse than baseline), spiky (intermittent peaks), regressed (worse since a change), or within budget. A latency budget is the allowance a path gets ("the 300ms checkout budget").
• Locating it: "the latency is in the database hop, not the app tier"; "it's a cold-start effect, first request only"; "round-trip time (RTT) to eu-west accounts for 140ms of it."

Weak:   The service got really slow this afternoon.

Strong: Search p99 went from ~200ms to 1.2s between 14:00 and 14:40,
        p50 unaffected, all regions. Recovered on its own; suspect the
        14:00 reindex, not confirmed.

Errors and availability

• Rates, not vibes. Errors are described as a percentage of requests with a window: "5xx rate is 4.2% over the last 15 minutes, baseline 0.1%." The conventional adjective is elevated ("elevated error rate"); spike means sharp and brief, sustained means ongoing.
• Classify before alarming. 4xx (client-side, often someone else's bug or an abusive caller) versus 5xx (our side); transient (retry fixes it) versus persistent; intermittent (comes and goes) versus reproducible (on demand, the debuggable kind). "It's a reproducible 500 on POST /orders with an empty cart" is halfway to fixed.
• Timeouts are their own species: "failing" and "timing out" are different claims; say which, and at what threshold: "not erroring, timing out at the 5s client limit."
• Availability language: "we burned a third of the monthly error budget in an hour" (the error budget being how much unreliability the SLO allows; see Chapter 12 for the SLA/SLO/SLI family), "the service was hard-down for 11 minutes" (completely unavailable) versus "degraded for two hours."

Throughput, load, and capacity

"It doesn't scale" is a verdict; capacity language makes it a description: requests per second (rps, or QPS), saturation (how close to the limit), headroom (slack remaining), and what you are bound by: "we're CPU-bound at about 900 rps; IO has headroom." Load descriptions carry shape too: steady-state versus burst, organic growth versus a thundering herd (Chapter 13 has the full stress bestiary). "The queue is backing up" plus a number ("depth 40k and climbing, drain rate half of arrival rate") is a complete capacity incident report in one line.

Data problems: leaks, leakage, and loss

Don't be confused: three phrases that sound alike and must never be mixed up. Data leakage is the machine-learning term for training contamination: information from the test set (or from the future) sneaking into training, inflating your metrics ("the model saw the label; classic leakage"). A data leak (or data exposure) is a security/privacy event: data visible to people who should not see it. Exfiltration is a leak with an active thief: an attacker deliberately extracting data. Saying "we have data leakage" in a security meeting, or "the model leaked" in an ML review, will produce ten minutes of cross-talk; pick the right term and, if in doubt, spell it out.

Describing a suspected leak or exposure, the four facts that matter, in order: category (what kind of data: PII, credentials, internal-only), scope (how many records/users), audience (exposed to whom: public internet, all employees, one wrong customer), duration (since when). "Customer email addresses (no passwords, no payment data) were readable by any authenticated user of any tenant, from the March 12 release until today's fix; roughly 40k accounts." Note the explicit negatives ("no passwords"): saying what was not exposed is half the value.

Data loss is yet another axis (the data is gone, not seen): describe it by recoverability: "lost but replayable from the event log" versus "unrecoverable."

Security language

Security wording is the one place in engineering where careless phrasing has legal weight; incident channels get read later by auditors, lawyers, and sometimes regulators. The professional conventions:

• The severity ladder of nouns: a vulnerability (a weakness) is not an exploit (working code that abuses it), which is not a compromise or breach (someone actually got in). "We have a critical vulnerability" and "we have been breached" are different emergencies; using the stronger word loosely causes real damage.
• Suspected versus confirmed, always marked: "we have a confirmed compromise of the CI runner" / "suspected credential stuffing, investigating." Upgrades from suspected to confirmed are announced explicitly.
• The evidence hedge, used honestly: "we have no evidence that customer data was accessed" is the standard formula, and it means exactly what it says: absence of evidence, from the logs we have. If the logs are inadequate, professionals say that too: "no evidence of access, with the caveat that object-level access logging was off."
• Neutral verbs in writing. During an active incident, write plainly and without speculation about actors or blame ("attacker" not "the hackers", "unauthorized access" not "we got owned"): facts now, color never. The channel is the record.

Code quality: smells and how to report them

A code smell is a surface symptom that suggests (not proves) a deeper problem; the term, from Kent Beck via Martin Fowler's Refactoring, is deliberately probabilistic, which makes it politer and more accurate than a verdict. Naming the specific smell beats adjectives, exactly as Chapter 5 predicts:

In a PR comment or design discussion the strong form is smell plus evidence plus consequence: "This class is heading toward god-object territory; the last four PRs all had to touch it, and reviewing it now requires holding all five workflows in your head." Compare "this code is a mess," which contains zero of those three. Adjectives like brittle (breaks under small changes), fragile, and hacky are usable shorthand between people who trust each other, but the named smell travels better; the full calibrated-criticism word list is in Chapter 14.

For tests and builds, the standard vocabulary: flaky (fails nondeterministically; the single most-used word in CI complaints), deterministic and hermetic (no outside dependencies) as the virtues, "the build is red/green", a regression (something that worked and now does not), and bisect (binary-search the history for the breaking commit): "flaky at about 3%, reproducible under --stress-runs 100, bisected to the pool change."

Marking confidence and scope, always

The habits that upgrade every description, whatever the domain:

• Mark measured versus felt: "per the dashboard" / "anecdotally" / "order of magnitude" / "back-of-the-envelope".
• Mark scope explicitly, including the happy part: "isolated to eu-west", "one tenant", "all writes", and the negative space: "reads unaffected."
• Timestamp claims in incidents ("as of 14:40") because they go stale while people read them.
• Round honestly: "roughly 40k" beats "41,237" (false precision) and "a lot" (no precision).

👉 With situations covered, the rest of the book is pure vocabulary. First the compressed layer everyone assumes you know: the abbreviations, from FYI and TIA to DRI and SLO, collected with tone warnings. On to Chapter 12.