In this chapter
We'll learn to communicate clearly at work — writing for your reader, leading with the conclusion, giving useful status updates, and asking technical questions that get fast, good answers — explained as calling a doctor's helpline with your symptoms ready.
The Problem in Real Life
Anna is stuck on one last review comment: a test that fails only in the pipeline. She posts in the team chat: "hi". Ten minutes later: "anyone free?". Then: "my test is not working". Nobody answers for an hour — not because they don't care, but because there's nothing they can answer.
John messages her privately: "Try this: write the message so someone could help you without asking a single question back." She rewrites it. Liam answers in four minutes.
Make it easy to help you, and people will.
John
Messages That Make People Ask Questions vs. Messages That Can Be Answered
"Hi" and wait
Messages without content cost everyone time and get slow answers.
Different readers
The founder, a teammate and a venue's developer need very different messages about the same thing.
Questions without context
"It doesn't work" can't be answered — the helper needs to know what, where and what you've tried.
Technical Communication and Asking Technical Questions
The doctor's helpline analogy: when you call a medical helpline, the nurse is fastest when you say: "I'm 28, I've had a fever of 39 °C since yesterday, a sore throat, I took paracetamol four hours ago, and I want to know whether I should see a doctor today." Who, what, since when, what you've tried, and what you need. Asking a technical question works exactly the same way.
- Know your reader: before writing, ask: who will read this, what do they already know, and what do they need to do with it? Samantha needs impact and decisions ("checkout is safe; no action needed"). John needs technical detail. A venue needs what changes for them and when.
- Lead with the conclusion: put the most important sentence first — the answer, the decision, or the request. Details come after, for those who want them. "The pricing PR is ready for review — it's split into three small PRs. Details below." Busy readers may only read the first line.
- Be specific and short: names, numbers, links and dates instead of "soon", "some users", "the thing". Use lists for steps and options. One message, one topic.
- Status updates — no surprises: a good update says what's done, what's next, and what's blocking you (Act 18's stand-up). Report problems early, with what you've tried: "I'll miss Thursday because the payment sandbox is down; I've asked their support; new estimate Monday." Bad news early is a gift; bad news late is a problem.
- Asking technical questions — the helpline call: a good question has: context (what you're working on); goal (what you're trying to achieve); what happens (exact error message, copied as text); what you've tried (and what each attempt showed); and a specific question. Add a small example or a link to the code. Post it where others can learn from the answer (a team channel rather than a private message).
- Don't ask to ask: "Can I ask a question?" or "Anyone free?" makes people wait to find out what you need. Just ask the full question.
- The XY problem: sometimes people ask about their attempted solution (Y) instead of their real goal (X): "How do I make the test wait 5 seconds?" when the real goal is "my test fails because the database isn't ready yet". Always include the goal, so helpers can suggest a better path.
| Part | Before | After |
|---|---|---|
| Opening | hi / anyone free? | Pricing PR #455: one test fails only in CI |
| Goal | (none) | Get the pipeline green |
| What happens | my test is not working | Expected 1147.5, received 1147.4999999999998 (log link) |
| Tried | (none) | Different timezone; npm ci from scratch |
| Question | (none) | Different Node version, or floats for money? |
| Time to answer | No answer in an hour | Four minutes |
| Reader | What they need | Message |
|---|---|---|
| Samantha (founder) | Impact and decisions | New pricing goes live Monday; venues see no change in how they book. |
| John (tech lead) | Technical detail | Three PRs; prices now in cents; tests cover every rule boundary. |
| Venues | What changes for them | From Monday, student groups get an extra 10% off — see the pricing guide. |
Anna's rewritten question: "Pricing PR #455: one test fails only in CI, passes locally. Goal: get the pipeline green. The test applies student discount after group discount fails with Expected 1147.5, received 1147.4999999999998 (log link). Locally it passes. I've tried: running with TZ=Europe/Berlin (Act 17 habit — still passes) and npm ci from scratch (passes). Question: could CI be using a different Node version, or am I comparing money as floating-point numbers?" Liam replies: "The second one — never compare money as floats. Store prices in cents (whole numbers) like the checkout code does." Four minutes.
Key Takeaway
Write for your reader: know who they are and what they need to do, put the conclusion first, and be specific and short. Status updates say done, next and blocked — and share bad news early. Ask technical questions like a helpline call: context, goal, the exact error, what you've tried and a specific question, posted where others can learn. Don't ask to ask, and include your real goal to avoid the XY problem.
Why This Matters
In most teams, communication is half the job — in pull requests, chat, tickets, stand-ups and emails. Clear writing gets you faster help, fewer misunderstandings and more trust. And asking good questions is a skill interviewers look for directly: "tell me about a time you were stuck".
Liam knew the answer — this time. But John wants Anna to be able to find answers herself, quickly, from the right sources: documentation, error messages, search and code.