bhargavk209 / explain-tech

Explain without dumbing down

Re-explain something so a reader with no engineering background can follow it, while keeping every technical detail the original had. Both halves matter. The second one is the half that normally gets sacrificed.

When to Use

• The user typed /explain-tech.
• The user asked for an explanation of something already on screen: "explain that again", "break that down", "walk me through it", "what does that actually mean", "ELI5 but don't dumb it down".
• The user wants a version they can hand to someone non-technical.

When to Skip

If the question is genuinely one line — "what does --sync do?", "which file was that in?" — answer it in one line. Wrapping a small question in a full explanation buries the answer. The signal is whether there is a mechanism worth unpacking, not whether the user used the word "explain".

Pick the Target

• No argument — the most recent substantive output: the analysis, table, diff, log reading, or recommendation. Not the closing "done, anything else?" line.
• An argument naming part of it ("the shard math", "the guard_miss bit") — explain that part, placed back in the context of the whole.
• An argument naming something else (a file, a PR, a command's output, a concept) — explain that instead.
• Genuinely ambiguous between two recent outputs — ask which, in one line. Don't guess, and don't explain both.

The Rule That Decides Everything

The reader's difficulty is in the vocabulary, not in the content. So lower the vocabulary and leave the content completely intact. Someone who finishes reading should know everything an expert reading the original knew, plus the words for it.

• Define every term inline the first time it appears — in a clause, then keep moving. Include terms an engineer would never stop to define: process, cache, queue, index, commit, pod, thread. A clause ("a pod — one running copy of the service") costs six words. A glossary section costs the reader their place.
• Never rename a real thing to a friendly thing. It is deploy/inference.yaml, not "the settings file". It is ER_DUP_ENTRY (1062), not "a duplicate error". Someone handed "the settings file" cannot find the settings file, and cannot search for it later.
• Never round, never collapse a range. "14.2 min → 8.6 cold / ~7 warm" keeps all three numbers and keeps the ~, because the ~ is the difference between measured and approximate. "About ten minutes" throws the finding away.
• Order instead of omitting. Plain meaning first, then the mechanism, then the exact artifacts — names, values, commands, references. A reader who stops early loses detail; they never lose correctness. That is the whole trick: layering buys readability, cutting buys nothing that layering doesn't.
• Keep the caveats. The conditions, the "only when", the failure mode. Those are the parts a non-specialist needs most, because they have no experience to reconstruct them from.

Moves That Make It Land

Work an example with real values. Take an actual number, log line, or id from the thing being explained and walk it all the way through. Show the arithmetic instead of asserting the result — a reader who can follow the multiplication believes the answer rather than taking it on faith. Invented examples ("imagine user 42…") are weaker than real ones, and real ones double as a check on your own explanation.

Analogies must name where they break. "It's like X — except unlike X, …". An analogy with no stated boundary stops being an illustration and becomes what the reader believes, and then it is simply wrong. If you can't state the breaking point, the analogy isn't ready to use.

Label fact vs. inference vs. estimate. Say which numbers came from config or measurement, which were derived (and show the derivation), and which are guesses. An experienced reader picks this up from hedging language. A non-specialist reads every sentence at the same confidence, so the labels have to be explicit.

Say what breaks without it. When the subject is a rule, an invariant, or a constraint, the reason it exists is usually the only thing that makes it stick. "Balance can never go negative" lands as arbitrary; "without this check, two withdrawals arriving in the same millisecond both pass and the user takes out money that isn't there" lands as obvious.

Traps

• Don't silently correct. Explaining is where errors surface — you will re-read something and find the original claim was wrong. Say so plainly and up front ("one correction before the explanation: …"), then explain the corrected version. Quietly explaining a different, better answer leaves the user believing the original was right.
• Don't re-investigate. Explain what is already in context. Re-read a file only to quote something exactly. If a claim can't be verified from what's there, label it as an inference rather than going off to check — checking is a different request, and this one was for an explanation.
• Don't pad. Length is proportional to what's being explained. A three-line answer becomes a paragraph, not an essay. Skip any part of the shape below that has nothing to say for this particular thing.
• Stay in the terminal. This is for the user to read now. If they say it's for someone else — a teammate, a manager, a ticket — offer a shareable page in one line instead of assuming.
• Don't restate and call it explaining. If a sentence would be just as opaque to the reader as the original was, it hasn't been explained, only reprinted in a friendlier font.

Default Shape

A starting order, not a template to fill. Drop anything that doesn't apply here.

1. The answer in plain language. Two or three sentences, no jargon, no hedging. What happened, what this does, or what to take away.
2. How it actually works. Step by step, in the real order, with the real names. Terms defined as they arrive.
3. A worked example. Real values from the actual thing, arithmetic shown.
4. Why it matters. What it buys, or what breaks without it.
5. The exact details. Paths, flags, numbers, commands, error strings — everything needed to act on it. This is the part a reader may skip. It is never the part you cut.

Examples

Example 1 — a performance finding

Bad (friendly, lossy):

The GPU box takes a while to warm up, but we got it down to about nine minutes. The problem was a caching thing — it's like a chef doing prep work the night before. We fixed it in the config file.

Four separate losses: the numbers are gone, "a caching thing" names nothing, the analogy has no boundary, and "the config file" cannot be found.

Good (same reading level, nothing lost):

Before the service can answer a request it has to warm up — do slow one-time setup work. That warmup used to take 14.2 minutes. It now takes 8.6 minutes from cold and about 7 when warm.

The slow part is torch.compile, which rewrites the model into faster low-level code the first time it runs. It is meant to save that result to disk so the next start can reuse it — like a chef doing prep the night before. Where the analogy breaks: the chef's prep is always usable, but torch.compile only reuses its saved result if the runtime conditions it recorded still match exactly. A mismatch is called a guard miss, and it redoes the entire job.

The fix was upgrading torch from 2.7.1 to 2.8.0, which took the cache hit rate to 6/6. One caveat worth keeping: production does not get this benefit, because its cache directory is an emptyDir volume — scratch space that is wiped every time the pod (one running copy of the service) restarts.

Example 2 — a capacity number

Bad:

We're handling a lot of jobs and there's plenty of headroom.

Good:

Measured over a full day, the four pods — a pod is one running copy of the service — handled 42,000 jobs. The GPU, the chip that does the actual work, was busy 71% of the time at the daily peak, so for roughly three tenths of the peak hour it had nothing to do.

The ceiling is about 110 jobs per minute. 42,000 jobs over 24 hours averages 29 per minute (42,000 ÷ 1,440 minutes), which is about a quarter of that ceiling. But the average is the less useful number: load arrives in bursts, and at the peak we are already at 71% of one resource. That 71% is the number to watch, not the daily total.

Both good versions are readable by someone with no background, and neither drops a single value the original carried. That combination is the entire point.

Longer Worked Examples

Full before/after pairs, one per input type. Read the matching one when the input is a kind you haven't explained before and you want the calibration:

• [examples/error-log.md](examples/error-log.md) — a crash traceback, explained without losing the stack, the exit code, or the fix.
• [examples/capacity-estimate.md](examples/capacity-estimate.md) — a numbers table, with the arithmetic shown and every figure labelled measured, derived, or guessed.
• [examples/code-diff.md](examples/code-diff.md) — a small diff, explained so a non-engineer understands what breaks without it.