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
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 regexSSCCE
Short, Self-Contained, Correct Example: the smallest code that shows the bug and runs on its own.
one file, one function, still failsminimal repro
The trimmed project that barely fails. Trimming often reveals the bug before anyone else sees it.
delete 90 percent, still reproducestl;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 buildshow it works
- 1Search 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.
- 2Lead with the goal
One sentence of what you are actually trying to do. This single line prevents the XY problem before it starts.
- 3Show the smallest code
Trim until it just barely fails. If the bug disappears mid-trim, congratulations — you found the interaction that causes it.
- 4Paste the full error
No paraphrasing, no screenshots of text. The exact message is what search engines and human experts index by.
- 5Add 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
side by side
answerable question
- goal stated in one line
- smallest code that still fails
- full error text and versions
- experts reply in minutes
'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
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