Asking good questions is a skill that all developers need. For this blog post I want to focus specifically on asking questions of developers at the same organization. When asking questions of people at your own organization, you are trying to save yourself time on figuring out the problem, but you also don’t want to waste everyone else’s time by forcing them to re-diagnose your entire problem. This is the simple checklist I use to craft good questions:
- Outer Context
- Quick Look
- The Task
- The Blocker
- Actions already taken
I’ll go into more detail for each point.
Understand The Outer Context
What area of the product, codebase, or build system are you working in? This may seem useless to the person asking the question, but it is very helpful for everyone else to orient themselves. Sometimes it will just allow the person being asked the question to say “I don’t know, you should ask so-and-so instead”. Other times it lets people know the priority of your problem, based on whether it might be impacting others. A problem with the build system might impact everyone. A problem in a shared component could be very important to address. But a problem in an isolated product area might be a lower priority. You can sometimes skip this step if you are working closely with a team member and they already know the context.
Example: “I am working on the edit user page, adding some new form fields, using standard components.”
Take A Quick Look
This is the part of the question that allows a reader to quickly track down where the problem is happening. It might contain part of the replication steps for the problem, links to the code repository, links to an error page, an error message, etc. Whatever is most relevant to immediately letting someone see the issue you are dealing with. All parts of the question should be as brief as possible, but definitely try to keep this part of the question as concise as you can. The reason why it comes second (and possibly first if you are skipping the outer context) is because it is the last ‘context check’ for the readers. They can still realize that they might not be able to help you based on what you link to, or that they should be quickly jumping on to help you.
Example: “Here is a link to my git pull request for the edit user page [link].”
Assess The Task
The task will be what you are trying to accomplish. This is an important part of the question, and often skipped to the detriment of everyone. It is important, because sometimes the task you are trying to accomplish is wrong, and you are encountering an error because what you are doing is incorrect. I’ve often had to ask people what task they are trying to accomplish only to find out they are unintentionally breaking accessibility, a web standard, or the functionality of another part of the product.
Example: “I am trying to add a birth date field, with a drop-down calendar.”
Identify The Blocker
This is what is stopping you from accomplishing your task. I won’t spend much time on this, because usually people know to include this part of the question. It is sometimes the only part of the question that is included.
Example: “When I select a date in the drop down calendar it doesn’t show up on the date of birth field.”
Provide Actions Already Taken
It is helpful to let people know what you have already done. This will usually be the most lengthy part of the question, and it will also let people know that you’ve tried the most basic things first. If you do this right there won’t be any questions like “have you done basic thing x?” and you respond “yes I have done basic thing x”. You might realize that you didn’t check basic thing x, and then realize that ‘oh dang I actually messed that up.’ So sometimes it is useful to construct this part of the question first.
- “I have googled the error message that comes up when I try to select dates, but nothing useful came up.”
- “I have looked at other examples of date fields in the application, and I think I am doing everything that they are doing.”
- “I’ve tried looking at the documentation for the calendar component, and I don’t think I’m doing anything wrong.”
A Good Question
Taking all of the examples together we have a short and concise question that can hopefully help others diagnose your problem quickly:
“I am working on the edit user page, adding some new form fields, using standard components. Here is a link to my git pull request for the edit user page [link]. I am trying to add a birth date field, with a drop-down calendar. I have googled the error message that comes up when I try to select dates, but nothing useful came up. I have looked at other examples of date fields in the application, and I think I am doing everything that they are doing. I’ve tried looking at the documentation for the calendar component, and I don’t think I’m doing anything wrong. Can someone help me?”
(or re-read my intro, it follows the format)