Alyssa’s Guide to Asking High-Quality Technical Questions

You’re trying to complete a technical piece of work. Something isn’t working. You’ve tried everything you can think of and you’re still stuck. It’s time to ask for help! The way you ask for help directly impacts the likelihood that you’ll get the help you need. Here’s how to ask for help effectively.

This document was last updated 22 FEB 2022

Start focused

• In one sentence, what one thing are you trying to do?

Include more context than you think is necessary

• Where are you currently trying to do it (i.e. your laptop, your personal development host, another host, the AWS console)?
• What package (respository) are you working on, if applicable?
• What packages (repositories) do you have in your local workspace, if applicable?
• If the error is the result of running a particular command, what exact command did you run?
• If the error is the result of running a series of commands, what is the complete series of commands (including the successful commands you ran before the failed commands, and the commands you intend to run after this command once it succeeds)
• What directory are you in? (pwd)

Explain what you’ve tried already

I like this format:

• This is the outcome I’m trying to achieve
• This is the command I ran / this is the action I took
• This is what I expected would happen
• This is what happened instead
• Based on that, this is what I did next...

Repeat until you run out of information to share

When did it last work?

• Has the thing you’re trying to do ever worked for you?
• If this has never worked for you (first time building a new package locally, or first time doing a test deployment, for instance), does it work for your teammates?
• If it has worked for you, when did it last work? (I’m going to give you a hint here — the answer to this question should be “very recently,” on the order of minutes to hours rather than the order of days to weeks. My day starts and ends by ensuring that my code builds and my tests pass, and I recompile and retest my code with every incremental change I make — on the order of dozens or hundreds of times per day)
• What has changed since it last worked? (A hint on this one, too — the answer to this question should be easy to sum up in a single sentence. If it isn’t, you’re likely trying to do more than one thing at once. Attempting to work on more than one thing at once makes it substantially harder to pinpoint what is causing which failure. What one thing are you trying to do?)
• Are you able to undo those changes? If you undo those changes does it start working again?

Share your reference material

• Provide links to documentation you are attempting to follow, if applicable
• Provide links to example code you’re using as a reference, if applicable
• Provide links to Stack Overflow questions you’re referencing, if applicable

On error messages

• If you have an error message, share the whole thing!
• If you can, try to point out which part of the error message is the important part (it’s okay to say, “I think that this line is the important part, but I’m not sure”)
• If you can, try to explain what you think the error message means
• Prefer sharing copy/pasted error messages rather than sending screenshots so that your helper can copy/paste your error messages into Google or Stack Overflow

Don’t time box, “due diligence box”

• There’s not a single correct amount of time to be stuck on a problem; the right time limit depends on the problem you’re working on and the skills you have to solve that particular problem on your own
• If you aren’t making progress and don’t know what to try next, it’s time to prepare to ask for help
• Preparing high-quality technical questions is part of doing our due diligence. When you can answer the bulk of the questions listed here, you’re ready to ask for help
• Doing the due diligence of compiling a high-quality technical question can help to organize your thoughts, and if you’re lucky it might even help you answer your own question

Sometimes this isn’t possible; sometimes it isn’t necessary

• Sometimes you just don’t know enough about what you don’t know to formulate the question you need to ask. That’s okay. Do your best to formulate high-quality questions, but if you can’t, it’s okay to say, “I’m just really lost right now.”
• Sometimes you have deep shared working context with another engineer. If the person you’re asking for help knows everything about what you’re working on, this level of detail may not be strictly necessary.

Take question-asking notes

• When you ask a question, what questions get asked of you in return?
• The next time you ask a question, try to include that information from the start

Yep, asking high-quality questions is a lot of work!

• Answering questions is also a lot of work!
• The more work that you do up front in asking your question, the fewer questions your helper will need to ask you in order to help you solve the problem — enabling them to answer your question faster.
• Beginners often worry about asking “too many” questions. Focus on quality and don’t worry about quantity. Answering high-quality questions is substantially less taxing than answering low-quality questions (which often require a helper to do additional information gathering on your behalf).
• If the error you’re encountering is really common, it’s possible you’ll luck out and someone will recognize it and know the answer immediately without any additional context. However, it can be hard to tell if an error is common or if it’s highly specific to your situation. When you don’t know if the error is common or specific, it’s better to assume that it’s specific and provide as much context as you can.
• High-quality questions show your helper how you’re thinking about the problem and demonstrate the effort that you’ve put into solving the problem yourself.
• High-quality questions earn trust.