"School is about giving the right answers to questions. Life, in contrast, is mostly about asking the right questions, to begin with." - Scott H. Young.
Regarding coding, we spend 80 % of our time asking questions and 20% executing the result. So, one of the skills many pro developers possess is asking good questions when encountering an issue.
This week I want to share some of the characteristics of good questions, and I will go over templates I used to draft good questions and analyze good and to-be-improved questions from stack overflow.
What Are the Characteristics of the Right Questions?
Do your Due Diligence
Before asking for help, try to find a solution yourself. While you should not feel afraid to ask questions, you should also be respectful of others' time and first try to see if you can do it on your own.
They might also realize that you have already tried every approach they know of, so they know they need to redirect you to someone else with more expertise.
Another tip I usually do is not to put the raw error message on the first thread but on the following smaller thread. I would summarize the raw message and mention the "raw message on threads below" for more context. If the questions are too long, you will be less likely to get any response back because no one has the time to read a long-form essay that leads up to a single question.
Here are some of the information you should be sharing to indicate you have tried:
Your understanding of the problem. It is important to articulate your thoughts and issue and what you have done to fix it.
Screenshot of the error or issue.
Code that recreates the issue (in the smaller thread description.)
Read and re-read your questions before posting online.
When you ask the questions, you can tell the other members what you have done so far and the research that you have conducted, and it doesn't work. This saves the other party time not going into all the routes you have tried. If they know certain approaches do not work, they can more easily identify methods that would work.
Provide a Context
A good question is very specific. For instance, when you are troubleshooting a bug, you give a context on what happens during the events of the system. Did you change something in the system, and an error occurred afterward, or one day an error occurred out of nowhere?
Why do we need to give context when asking questions? Because in every context and community, the same "answer" can look different. Each individual will interpret your questions in their way, and they may answer the questions with the assumption of the context. Giving them the context helps save their assumption time and gives you the answer you want.
Context helps ensure that the questions are relevant to the situation or problem. By providing context, you can ensure that the question is tailored to the specific circumstances, making it more likely to receive an appropriate response.
Consider these two ways of asking the same questions:
"I am not able to send my campaign. Can someone help?"
"I was trying to send a one-time-sent campaign at 2 PM yesterday with X title. I have waited a while, but the campaign seems not to be delivered to my target audience. This is my campaign ID, 12223. Can someone please look at what happened to this campaign ID?"
The first approach requires a longer response time because no context is given. On-call engineers are very busy, and if they see a question that requires additional back-and-forth clarification, they will put that question at the back of the queue and answer the next one, which contains a greater enough context.
Providing a Purpose
The time for carrying out research and analyzing results is always limited. Knowing your most essential question(s) will focus your time where you feel it is most valuable.
When I was presenting a spike to my team, there often were questions that asked to sound like they were testing all the scenarios and knowledge of the topic. However, sometimes, these questions can be out of the blue. For instance, Verticals want our team to integrate with an external authentication service, and I scheduled a meeting to go through the integration steps.
When I explain the steps required to integrate our service with an external authentication flow, someone will ask, "Why is the authentication flow done this way?" or "Why do we use this X for our authentication flow?" I may not know the answer to these questions. However, I often responded by saying, "Why do you ask?". This gives clear guidance on the purpose of the questions to easily direct them to the right answer.
If you don't know why you are asking questions, delete it. Not all questions have to support the research outcomes directly. For example, ask questions to ease a participant into the session. However, knowing why you are asking these questions will help you limit your time on them.
The key to asking good questions is to decrease the time spent on follow-up questions.
Templates on How to Draft a Good Question
Below are some of my check-list and orders for drafting a good question:
The "problem" that you encounter and the context
Your thoughts on what you think might be wrong "based on your research."
Proof of research efforts. Take a learn and clear screenshots where necessary.
If it is on a Slack channel, end with "Please let me know if this is not the right channel to ask!"
Let's take one stack overflow as an example: this developer has a problem defining case classes when using Akka Actors.
He gave context by mentioning the purpose of the action - downloading an image with PhotosLoaderActor and saving it into the cache.
Then, based on his research, he described his thoughts on what to do.
He gives a little coding snippet as a reference that he has done some proof of research.
By now, this question has all the tenets of good questions, providing due diligence, context, and purpose.
He ended the thread by asking the questions - where should he put the piece of code, and what will be the best practice?
Let's take another example of a stack overflow question that doesn't provide enough context.
This user encounters an error trying to install the Firebase stripe payment extension with an error. This user then copied and pasted the raw message on the questions and gave some context that he installed it manually via the console.
To clarify these questions, he can discuss more what installation guide he has followed, with the link pasted. What kind of action has he taken to get into the problem, and some research effort (steps he did himself to troubleshoot the error) that include other Stackoverflow threads?
To change this into better questions, we can start by saying:
Hi team, does anyone ever encounter a "Too many concurrent builds" 429 error when installing the Firebase stripe payment extension in their Chrome? I tried the [google cloud manual installation guide] by first doing X, Y, and Z. When I try to run A, it throws too many concurrent build exceptions (screenshot below).
More information about my machine:
Chrome Browser version: 1.0.2
GCP console version : 0.0.2
I tried to do BCD according to this stack overflow (attach the link here), but it still gave me the same error.
Please let me know if there is any more information that is needed. Thanks in advance!
The questions above require a lot more effort to write. However, it also gives much information upfront to save someone who wants to help you answer the questions.
First, the questions above ask questions upfront if anyone ever made an entire 429 error when installing the Firebase stripe payment extension. This has already given away a lot of context in a single sentence. The user encounter error when installing the Firebase stripe payment extension, and the error is 429 or Too many concurrent builds.
Next, the user goes deeper into what they did - the manual installation guide- and describes observing the problems. Moreover, the user also mentioned the build version of their machine to provide how to reproduce the error and save their helper's time in follow-up questions. The user has provided a purpose to the questions and context by now.
Lastly, the user mentioned that they have tried to resolve the problem according to the stack Overflow link and found no luck.
Recap
Asking questions are 80% of the job of software engineers. Good questions can help you decrease your response time.
Asking questions is natural when encountering a problem, but before reaching out to the developer community, it is important to try and solve the problem yourself as much as possible. This shows that you value the time of your teammates and the developer community. Providing all necessary information, like code snippets and links so that helpers can reproduce the problem with minimal effort is always helpful. Remember to communicate the purpose of your question. This will enable developers to provide targeted and insightful answers to your problem.
Try to solve the problem first before asking questions. This helps not to abuse the developer community's help and earn your teammates' trust that you are mindful of their time. You are adding as much information and linking any code snippet so that the helpers can have minimal reproduction without sacrificing their time setting up the project. Lastly, give the purpose of your questions so that the developers answering the questions can give a better answer to your question.
Just like all skills, writing good questions requires constant practice and receiving consistent feedback. Keep refining your question by describing the "problems" you encounter, your thoughts on what you think about the problem, and the proof of research. I have crafted a good questions template.
What are some tips that you have done to construct great questions? Please comment on them down below!
💡 Want more actionable advice about Software engineering?
I’m Edward. I started writing as a Software Engineer at Disney Streaming Service, trying to document my learnings as I step into a Senior role. I write about functional programming, Scala, distributed systems, and careers-development.
Subscribe to the FREE newsletter to get actionable advice every week and topics about Scala, Functional Programming, and Distributed Systems: https://pathtosenior.substack.com/
Top comments (0)