- 1.
Try a reasonable amount1 to help yourself before you take others’ time.
- 2.Provide ample context, as you would with any other form of technical writing:
Your intentions: What you’re trying to do so your colleague knows why you’re asking and can decide whether the question is the right one to ask in context.
Your observations: Things that you have seen with your own eyes, as described in Knowing Our Limits (Chapter 7). Data that can be used for meaningful inference.
- 3.
Express your question as precisely as you can: you should aim for some sort of actionability, no matter the nature of your question; your collaborator should be able to answer or act on the question as completely as possible based solely on what you’ve captured.
Here’s a bad question that you’ll see asked a hundred times:
I saw a problem deploying this service. Do you know what might be wrong?
Here’s a much better question:
I’ve been trying since 1 pm to deploy a logging change to the User Service (commit f752e2ee8) with the Prod Deploy Jenkins job. I see that the job fails, and there’s an error message in the Jenkins logs about artifactory not accepting a connection. I think the job is configured correctly—do you know how to check whether artifactory is healthy?
Maybe you’re not at all familiar with how to get at the job logs (or some other part of the chain of analysis); you can still ask a more precise and actionable question than “help.” Here’s another fine question:
I’ve been trying since 1 pm to deploy a logging change to the User Service with the Prod Deploy Jenkins job. I see in the UI that the job fails, but I’ve never used Jenkins before, and I’m not sure how to find the logs. Can you walk me through how you’d normally debug an issue like this?
Actually, molding beautifully precise questions is an art that must be mastered over time. Luckily, I think the majority of technical questions can be expressed clearly with one of a few simple “magic templates” that naturally bundle up context in the question.
Magic Template: Asking for Help Debugging
The template:
I’m trying to <goal>. I’m doing <actions>, but I see <observations>. My best theory is <theory>, because <reason>. Can you <do something specific>?
Example:
Hi Shahrooz,
I’m trying to add a new endpoint for kittens to the cat service; the diff is here. I’ve added the handler to handlers.js and am running the service locally with “make run-local” as per this doc, but when I try to query the new endpoint with curl -v localhost:8888/kittens/tabby, it fails with a 404 and an empty body. I don’t see logs from my endpoint in the log browser. I’m wondering whether I missed a step to add the endpoint. Does anything jump out at you that I may have missed? If not, do you mind reviewing the diff with me? I can set us up some time. Thanks!
Cheers,
DH
<goal>: Why you’re trying to do this thing at all (maybe they know a better approach!).
<actions>: The exact steps that led you to what eventually happened. This lets them construct a mental model of the state of the world at the time of the observation; it also shows that you’ve really tried to tackle the problem on your own (see Just Do Something in Chapter 5).
<observation>: What you saw with your own two eyes. Armed also with the knowledge of what they did to get there, they can now theorize as to why it’s happening.
<theory> <reason>: What you’ve reasoned through so far, which may be important to explain why you’ve come to this specific person for help. If you don’t have any theories, you can say that. It also shows your helper that you’ve attempted to reason about the problem on your own.
<do something specific>: You should come with the most actionable request you can, not just explain the situation and stop. That request may be as general as, “can you please look at the logs with me and see if you see anything,” but it should be something the other person can act on; you’re both giving them the last piece of the context and showing that you’re not trying to hand off initiative like a child to a parent (“here I am! Do my work!”) but rather have a well-reasoned purpose in taking their time.
You’ve explained what you want, what you truly know, what you merely suspect, and what exactly you want your colleague to do; you’ve included links to key background so they could swiftly answer any obvious questions about your story. They’re amply armed with context and ready to help, even if that means suggesting an overall new approach to your problem.
Magic Template: Asking For Help with a Production Issue
The template:
We’re observing <observation> starting at <time with time zone>. It is likely causing <experience> for <percentage> of <class of users>. We think <theory> and want help <doing|investigating> <thing> to mitigate>.
Example:
We’re observing elevated errors on the log-in endpoint starting at 12.30 pm PT. It’s likely causing as many as 30% of all customers to fail to log in right now. We’ve seen log messages about query failures and suspect the database might be struggling. We’d like to ask you to join the video conference and take a look at the DB.
Explanation:
<experience> <percentage> <class of users>: Other systems operators need to understand exactly what the business impact of an issue is to reason about risks and benefits of actions, which must include understanding what users are affected and how.
<time with time zone>: Understanding impact and correlating events require knowing how long the problem has gone on, and since people may be distributed across time zones, you do well to always include them.
Magic Template: Everything Else
You get the idea. Say what you’re doing, say what you’re seeing, say what you think, and ask for the most specific action you can.
The template:
I’m trying to <do a thing>. I <have done some things | already know some things>. To move forward, I want to <do or know something else>. <specific question>.