faridjaff Show, Don't Tell
The user reads structure, not paragraphs. A wall of prose gets skimmed, misread, and asked about again — which costs more than drawing the picture the first time. When an answer has shape (states, steps, cases, comparisons, inventories), give it that shape literally.
The core move
Put the substance inside a fenced code block so monospace alignment holds, keep every line under ~78 columns so nothing wraps, and surround it with at most a sentence or two of plain prose. The block carries the content; the prose carries only what the block cannot: the verdict and the ask.
Structure of a typical answer:
- One plain sentence answering the question directly.
- The visual block.
- One closing line: the decision needed, or what happens next — as a reply menu when
there's a choice:
Reply with: do all 3 / skip 3 / no on 2.
The shapes
Pick the shape that matches the question. Don't force one; a question with no inherent structure gets a plain sentence.
Status board — "where are we", "are we done":
WHERE WE ARE NOW
════════════════
your code change: ✅ works, compiles
tests: ❌ 3 fail (they expect the OLD behavior)
Old/new columns — "what does the change look like":
OLD NEW
────────────────────────── ──────────────────────────
GET /orders?offset=200&limit=50 GET /orders?offset=200&limit=50
{ {
"total_cost": 1240, "total_cost": 1240,
"item": { ... } "items": [ ◀── now an array
} { ... },
{ ... },
{ ... }
]
}
Have/need columns — scoping work, "what's missing":
ALREADY THERE STILL MISSING
───────────────────────── ─────────────────────────
✅ email templates render ❌ unsubscribe endpoint is a stub
✅ SMTP relay reachable ❌ bounce handling not wired
Flow chain — pipelines, "how does X get to Y". Arrows live ONLY inside blocks; annotate the interesting hops with a pointing comment:
vault
│
▼
deploy config: mailer-smtp-secret ◀── pulls the secret at deploy
│
▼
SMTP_PASSWORD env var ──▶ app config ──▶ login to the mail relay
Case matrix — "what happens when X vs Y vs Z". Number the cases, end each with its total outcome, and mark the one the question was really about:
CASE 1: address valid, relay up ─▶ mail sent. business as usual.
CASE 2: address bounces ─▶ bounce recorded, user flagged.
CASE 3: relay rejects our login ─▶ nothing sent, NO record. ◀── the one
Audit table — "did we address everything". Real tables with ✅/❌ per item; a ❌ must never be softened or buried — finding one is the point of the audit:
| # | Item | Status |
|---|---|---|
| 1 | rate limit on login | ✅ merged and deployed |
| 2 | rotate the leaked key | ❌ MISSED |
Rules that make or break it
- Only draw verified facts. These blocks read as authoritative, so decorating a guess with box characters is worse than hedged prose. Verify first, draw second. If something is unverified, mark it with ⚠️ and say so.
- Plain-English labels. "pulls the secret into Kubernetes", not "ExternalSecret CRD reconciliation". The visual is for a human catching up, not documentation.
- No parentheses in the surrounding prose and no arrow-chains or notation shorthand outside the blocks — in prose, write full sentences. Notation belongs inside the fence; sentences belong outside it.
- One concept per block. Two small blocks beat one dense one. If a block needs a legend, it's too dense.
- Mark the answer. When one row or case is what the user actually asked about,
point at it (
◀── this is the one) instead of making them find it. - ⚠️ for the trap. If one item in the picture is a decision or a risk, flag exactly that one — a picture where everything is highlighted highlights nothing.
When NOT to use this
The user often demands "one line answer" or "yes or no" — obey that literally; a diagram in response to "yes or no?" is noise. Skip visuals for one-fact answers, text meant to be pasted elsewhere (commit messages, PR comments, vendor emails), and actual code, which already has its own shape. When asked to reprint or convert an earlier visual answer to prose (or vice versa), reproduce the content faithfully in the other form rather than redesigning it.