Asking Effective Questions

Why even bother?

Asking questions effectively means that the person helping you will be able to answer your question better and quicker. Being able to answer a question quicker means more time to help others, including your future self. When questions require clarification, fewer people will be helped overall. Sometimes this in unavoidable because the question is complex, but all too often it if because the person trying to help is not able to reproduce problem, or the question is unclear.

When you are asking for help online, e.g. on StackOverflow or on GitHub, remember that you are often receiving help from people who are volunteering their time. So please make it as easy as possible for them to help you.

You might be frustrated by a problem to the point where you just want to ask something like.

WHY IS THIS **** CODE NOT WORKING??????

Don’t do this. No one will help you. You will get more frustrated.

When I feel like this, I find it really helpful and calming to sit down and type out a proper question. You can start banging out words in the beginning, but as you slowly adhere to the format of asking properly, it will become like a meditative practice which also calms you down.

In addition to your mental wellbeing, writing down questions properly has another superb quality: they help you solve your own problems. The act of formulating a question in either speech or text helps you uncover what you missed while the problem was a mere thought. This is so common that it has a name: “Rubber duck debugging” allegedly from a software developer who put a rubber duck on their desk and whenever they had a problem they couldn’t solve, they starting talking to the toy duck, and often came upon the resolution during while describing the problem.

How to ask effectively

In essence, you want to make your question as easy to understand as possible and your specific problem as easy to reproduce as possible. If you just include a screenshot and title your question “Help”, the person helping you has to spend time trying to figure out what you actually want help with instead of helping, Instead include a succinct, clear description of your problem and the minimal code needed to reproduce it. If you are asking your question on stack overflow you can use tags to categorize it, and these can then be used to search for an answer via the syntax [tag-name]. This can be especially useful for R, since the name is just one letter and it can be hard to find relevant matches otherwise.

Minimal reproducible example

There is a Swedish expression: “beloved child has many names”. No, it does not translate very well to English, but the message is that someone or something that many people like, will be referred to differently by different people. This is true for minimal reproducible examples, which you might find referred to by any of the following:

  • MRE Minimal Reproducible Example
  • MCVE Minimal Complete Verifiable Example
  • MWE Minimal Working Example
  • reprex REPRoducible EXample

There have been great articles written on what goes into an MRE, and here are some of them that I recommend that you check out:

In summary, asking effectively and creating an MRE includes the following tasks:

  1. Search for other questions similar to yours.
  2. Describe the issue clearly in the title and elaborate briefly in the text body.
  3. Reduce the code to the minimum required to recreate your error, and paste it as text.
    • If your code includes functions or classes, include their definitions.
    • Create small toy dataset instead of using real data.
    • Use markdown code blocks for proper indentation and syntax highlighting.
  4. Describe what you have tried so far, what you don’t understand or what went wrong, including any error messages and their full traceback.

The points are elaborated on below:

  1. Search for other questions similar to yours. Many questions already have an answer, and finding it is faster both for you and for others. If the answer to an existing question is not good enough, improve it by adding the missing info!
  2. Write the tile as a summary of your issue. Think about what you would want the title to say if you were searching the issue list for help. Just “Error” or “Question” is not helpful, but “How to list content in a folder?” is.
  3. Introduce the problem by briefly describing what you want to do.
  4. Show what you have tried, explain what you expected to happen, and what went wrong. It is often critical that the person helping you can reproduce the problem, so include both the code or command you tried to run and the error message.
    • For coding questions, text is preferred over a screenshot since it is easy to copy and paste, which facilitates reproducing your problem.
    • Inline code should be surrounded by single backticks for clarity. Longer blocks of code with multiple lines should be surrounded by triple backticks.
  5. Include versions of any packages you are using, and the operating system if relevant, e.g. Win10, Python 3.8, pandas 1.0.2. On R you can use devtools::session_info() to see this information (after install.packages("devtools")). and on Python you can use sinfo() (after importing: from sinfo import sinfo, needs to be installed via pip install sinfo).
  6. When your problem is solved, acknowledge the solution, close the issue/ticket/question. If you found the solution yourself, post it in a comment before closing, so that others can find it.