Invest time into writing questions: Tips for writing better questions
July 18, 2021
The essence of writing code is problem solving. This problem solving will often be a solitary task, you, the keyboard and a code editor. Not all problems are easily solved in this vacuum. For many problems we will benefit from the help of others.
Every problem or task when writing code is a chance to learn from others. A complex task can usually benefit from the input of multiple developers.
The more effort we put into asking a question, the more likely we will get an appropriate answer. When posing a question, whether this be over slack, email or in person, we should think of the time put into asking this question as an investment. A poorly framed question with little context will likely yield low quality answers, if any at all. A well structured question that describes the problem in full is far more likely to be answered well. With that, let’s look at how we can ask better questions.
Asking good questions is all about context. We should frame the question with as much information as we can. When asking online you will likely need to give more context that when asking within a team. The same rules generally apply to either scenario though.
1. Include information on the environment
A key piece of information will always be where this software is running. Is this a performance issue in production? Is this on your local machine? Documentation should be provided with any steps required to set up the environment.
2. Your issue should be reproducible
If there are some UI steps required to reproduce a bug, be specific about these. Include the branch name if relevant. Always have your code pushed to a remote repo.
If you are asking online (stack overflow), create a reproducible code sample on Codepen, Code Sandbox or some other publicly available sandbox.
3. Include errors
Don’t stop at describing the issue. Include any stack traces from logs or console output. Check the network tab for any related network errors and include anything that is relevant
4. List the steps you have taken
Give information on what you have already tried. What commands did you run? What code did you change? What debugging did you do? This will help frame the question and narrow the focus by eliminating these steps.
5. Link to code
When the question is on a specific piece of code, link to this in github or give a file path and line number. Don’t just give a function name. Help other developers find the code you are referring to.
6. Explain the problem in full
For more general questions on what technology or a library to use, explain what you are trying to achieve. List the things that matter as well as what matters less. Include any constraints you may have.
- Ensure you give enough information so that the same state can be reached in the application
- Add as much context as you can