Asking Questions

“It doesn’t work” helps nobody. Here’s the format.

▶ the lesson · narrated sketch video · tap for sound

the intro

A good question is a gift to the person answering: context, what you tried, what happened, what you expected. Teams answer well-formatted questions in minutes and vague ones in days. The skill compounds — good askers learn faster.

fun fact ✦

The XY problem: you ask how to do Y, but your real problem is X. Y was never the answer.

the docs

the deep dive

the ideas behind the video — concepts, diagrams, a walkthrough and the traps to avoid

Here is the part nobody says out loud: a well-formed question is the debugging method wearing a different hat. Goal, what you tried, expected versus got — that is reproduce, isolate, hypothesis in a trench coat. The reader can only answer what the message contains, so the message is the product; experts answer the question behind your question, and the format is what makes that question visible.

the format is the debugging

good questioncontexttried alreadyexpectedgot instead
four parts, zero follow-up threads: each one removes a round-trip

key terms

XY problem

Asking how to do your workaround Y when the real problem X has a two-line answer. State the goal first.

wants .txt stripped, asks about regex

SSCCE

Short, Self-Contained, Correct Example: the smallest code that shows the bug and runs on its own.

one file, one function, still fails

minimal repro

The trimmed project that barely fails. Trimming often reveals the bug before anyone else sees it.

delete 90 percent, still reproduces

tl;dr line

A one-sentence summary at the top, so a busy expert can triage your question in five seconds.

tl;dr: 500 only on prod builds

how it works

  1. 1
    Search first, then prove it

    Fifteen minutes of searching is the expected minimum, and one line like "searched X and Y" shows it. It also steers helpers away from your dead ends.

  2. 2
    Lead with the goal

    One sentence of what you are actually trying to do. This single line prevents the XY problem before it starts.

  3. 3
    Show the smallest code

    Trim until it just barely fails. If the bug disappears mid-trim, congratulations — you found the interaction that causes it.

  4. 4
    Paste the full error

    No paraphrasing, no screenshots of text. The exact message is what search engines and human experts index by.

  5. 5
    Add versions and platform

    Language, framework, OS. A shocking fraction of all questions die quietly on a version mismatch.

the code, explained

the four-line template: goal, tried, expected versus got, environment

1Goal: rename uploaded files by date
2Tried: fs.rename in a for loop
3Expected: files renamed, no error
4Got: ENOENT on 3 of 40 files
full error text, never paraphrased
5Node v20.11, Windows 11
versions up front — mismatches die here

side by side

answerable question

  • goal stated in one line
  • smallest code that still fails
  • full error text and versions
  • experts reply in minutes
VS

'it doesn't work'

  • no goal, no code, no error
  • a screenshot of plain text
  • the entire 300-line project
  • the thread dies in silence
🪤 gotcha

A 300-line code dump reads as "debug this for me" and gets scrolled past by exactly the people who could help. Trimming to the smallest failing case is not overhead before the real work — it is the real work, and it answers half of all questions on its own.

quick answers

Slack, GitHub issues, or Stack Overflow?

Match the venue: team chat for project-specific context, the library's issue tracker for confirmed bugs, public Q&A for general technique. The four-part format works identically in all three.

What if nobody answers?

After a day, reply to your own thread with what you tried since posting. Threads showing motion get answers; silent ones get buried under the feed.

Is a minimal repro really worth the effort?

It is the highest-leverage ten minutes in the whole exchange. Most askers find the bug while trimming and get to delete their own question — the best possible ending.

quick hits about Asking Questions

short answers · interviews, tips, trivia & hidden gems

🎤 interview

The format that gets answerswatch ↗

📚 tutorial

The four-line templatewatch ↗

💎 deep

The XY problemwatch ↗

💎 deep

Answering others teaches youwatch ↗