Friday, December 3, 2021

Help people help you and put in some effort

This article is for you if you either:

  • Created an issue or bug report that boils down to “XY doesn’t work. Help me”
  • Entered a chat room and wrote “XY doesn’t work. Help me”
  • Trying to get help but nobody is answering

Why you are here

I maintain a bunch of projects and as such I frequently triage issues. I usually don’t mind this. In fact it is the opposite: There is something satisfying about helping other people and I am grateful for users who help make the software I am working on better. But there is one aspect that is frustrating: If I have to exert a lot of energy to get all the information I need from the user. I don’t want to feel as if I have to fight to get useful information from a user.

Looking from the other perspective: It is also tedious for the user. It requires more back and forth and it takes longer to resolve the problem. Why do users report problems? Because they want their problem solved. If you are this user, please read on to see how you can help others help you.

How you can help others help you

It’s not always obvious what information you have to provide in order for somebody to be able to help you. Fortunately, there is an easy recipe you can follow. This recipe is generic enough that you can apply it any time you’re trying to get help:

  1. Explain what you’re trying to achieve using precise language.
  2. Explain what you tried and describe what you’re observing using precise language. “It doesn’t work” is not precise. “After I invoke X nothing happens” is. If you get an error message, include the full error message don’t abbreviate or summarize it.
  3. Explain the behavior you’d expect to see. Use precise language.
  4. Check if the application generates log files. If so, include them.
  5. Try to isolate the problem. If you can reproduce the problem, try to remove as many variables as possible. If you encounter the problem while working on a large project, see if you can reproduce it on a smaller project. Share as much as you can to help reproduce the problem.

Last but not least: If the project has an issue template, fill out all the information. Don’t ignore it. The template is there because the maintainers learned that this is the information they need. If you ignore it, they likely won’t be able to help you or won’t have the motivation.