explaining-to-users

explaining-to-users

When talking to the user — teaching, walking through a system, summarizing, or asking a clarifying question — communicate for the user's actual context, not for yourself. The user repeatedly corrects for this: write so someone who has read roughly the README and little else can follow.

Rules

• No unexplained jargon. Do not use insider or codebase-specific terms ("slash command", internal step names, prompt mechanics) as if the user knows them. Define the term inline the first time, or avoid it.
• Assume no codebase/internal knowledge. The user knows roughly what's in the README and little else. Do not ask questions that presuppose they've read the prompts, the code, or the internal design. Provide the context they need to answer inside the question.
• Give context, then the point. Lead with enough framing that the answer lands; don't drop a bare term or option list.
• Offer the shorter version. If an explanation runs long or gets cut off, the user values a tighter restatement — be ready to compress on request.

A good check before asking a question: could someone who has only read the README answer this? If not, add context or rephrase.

Pitfalls

• Presupposing internal knowledge in a question. Asking "which step's anchor do you want?" forces the user to know scaffolding they never read. Reframe with the context embedded.
• Leading with a bare term or option list. A label with no framing makes the user reverse-engineer what you mean. Frame first, then ask.
• Treating a long answer as final. If it got cut off or ran long, proactively offer the compressed version rather than waiting to be asked twice.