The open source community depends on the efforts of a small group of volunteers relative to the number of users. In order to make the most of contributors' time, here is some advice for asking “good questions”. This is largely paraphrased from this article by Eric Steven Raymond and Rick Moen, with edits for brevity and tone. If you have the time (and tolerance), I strongly recommend reading that article over this one. Let's start with the procedure.
- Try to find an answer by searching the archives of the issue-tracker, IRC, matrix-room, discord, forum or mailing list you plan to post to.
- Try to find an answer by searching the Web.
- Try to find an answer by reading the manual.
- Try to find an answer by reading a FAQ.
- Try to find an answer by inspection or experimentation.
- Try to find an answer by asking a skilled friend.
- If you're a programmer, try to find an answer by reading the source code.
- If you follow the above procedure, you are much more likely to develop a healthy working relationship with the open source community. There are people who consistently use this approach to asking questions, and I love helping them! I will spend hours addressing their bugs, and responding with targeted one-on-one help.
- When you don't follow this procedure, you'll likely get chastised and told to RTFM
- You may end up maintaining an open-source project one day, and you will be glad that you set a positive example for others when you experience the jadedness and fatigue that sets in after answering "bad" questions.
Q: I don't have the time. I'm a student. This seems too hard. I'm not a programmer. I'm not smart enough.
A: Have more faith in yourself! The odds are the human being you are asking this question to will repeat the above procedure. If you don't do it, that time will instead come from someone else who is following the exact same procedure. That person is likely busy fixing bugs for the software you are currently using. Please have empathy for your fellow human being.
Q: I found something that looks like the answer, but I don’t understand it.
A: That's ok! Ideally, you should repeat the above procedure for each thing you don't understand, and you will learn a lot! In some cases, you will eventually hit a roadblock. I've spent hours recursively searching manuals until I found the answer I was looking for. If you spend more than 4 hours researching a given question, I would say it's time to concisely summarize the state of your knowledge and use a help channel.
Q: When should I ask a question?
A: If and only if you have exhausted the above procedure, made no discernable progress, and have given it time to consider other alternative approaches to the above procedure, then consider asking the question. First try a community resource such as a discourse, discord, matrix, gitter, or another public medium before creating an issue. Keep in mind any question you ask will come out of the maintainer's time to review, time that could be spent maintaining the project or answering more valuable questions.
Q: What does an effective question accomplish?
A: An effective question adds value to the project for the maintainer, other users, and yourself. It should serve as an example to community members on what an effective question for this project should look like. An effective question shows you put in the effort to find the answer yourself as your insight will be a dead giveaway. Following the above procedure will give you more insight into the problem to draw upon in forming your question, and it shows the maintainers that you value their time and are not relying on them to do the problem solving for you. A great question provides the maintainer insight to apply to future development and documentation for the project later.
Q: What does a bad question look like?
A: [[link]] This question is bad for two reasons. One, it was asking an easily searchable question already in the docs. Two, it wasted the maintainer's time doing the work for the user.
Q: What does a good question look like?
A: nrepl/nrepl#108 This question resulted in a productive discussion that lead to added work (even supplied by the person asking the question for bonus points) that future users can enjoy. The maintainer was motivated to help answer it instead
Q: How does following this procedure benefit me and the maintainers?
A: Following the procedure above is key. As insight builds up, over time you can solve more of your own issues, maybe even develop a strong level of insight to meaningfully contribute to the project or help answer other users' questions resulting in a relationship the maintainer, community, and you can benefit from continually.