Asking for help is one of the easiest and most efficient ways to contribute to OSS projects - if you do it right. Last week I discussed code contributions, which is not easy and often takes a lot of time for beginners. With these tips, you can get your own problem solved and also help the project, more than you might think.
With the right questions, on good forums, you often help other users as well. Also, you might toward attention to something that needs to be improved. It may be a bug fix, enhancement or improving documentation. People quickly become blind to things they watch from too close. Sometimes simple questions from novices can lead to significant improvements in the project.
There are no wrong questions, but there are sometimes questions that may irritate the persons who have the best answers. Here are 5 tips to get your answer faster, along with the greatest aid to the project:
- Use the right forum
- Google before asking
- Use a clear and precise issue description
- Provide a reduced test case
- Explain the context
Let me explain why these are important and why you should pay attention to these.
1. Use the right forum
There are different kinds of issues, questions, and forums where you can seek for assistance. Try to find the most suitable for your case. The grand rule for all communication in OSS projects is: keep the communication open. I’m getting a lot of requests to help with Vaadin (Java web UI framework) related issues via private email, but I always try to forward the discussion to our open forum. This is not to humiliate the one asking for help. It is to document the solution for all others, who might face the same issue in the future.
So which media to use then?
Bugs and enhancement ideas
If you are familiar with your project and you have an apparent bug or enhancement idea to report, use issue tracker (GitHub in Vaadin’s case). If you don’t know whether you have found a bug or are you just “holding it wrong,” it is probably better to use another forum.
Generic help and discussion
Many open source projects have active forums or mailing lists. Those are often the best places to ask for, and also to seek for, answers. Some projects have moved to use StackOverflow solely.
Basically, any open channel that reaches the right people should be fine, but the ones above are most likely the best ones. One tip though: don’t use Twitter. 140 characters just aren’t enough for discussing technical issues. Twitter (or other social media or even email) is fine, though, to draw the attention of particular people that you think might have the answer. For example, don’t hesitate to ping me about a Vaadin issue, in GitHub or on our forum, that you think would need more love.
2. Google before asking
When using popular OS products, there is a high chance that somebody else has faced the same issue. In the past I have helped dozens of Vaadin developers by asking if they remembered to recompile the widgetset. Google the issue first. You might have missed the solution from the manual, or there might be a perfect answer in StackOverflow. Give kudos to the answer (thumb up or tweet about a helpful resource) and continue.
Don’t vigorously seek the whole internet for the answer. If you can’t find the solution quickly, it probably helps the project to ask the same thing in different words. Even if the answer would be “this is already answered here”, there is now a high chance that the next user will find the solution without asking. And if something is asked often, maybe the maintainers should think of better ways to make usage easier. In the widgetset case I referred earlier, we finally added instructions to recompile the widgetset in the error displayed to the developer.
3. Use a clear and precise issue description
When explaining your issue, try to use clear language and a precise description. Active OS enthusiasts may skim through hundreds of questions per day, and they have a lot of interesting problems on their TODO list to solve. They will often ignore the questions they don’t understand. Provide a clear title, a precise description of what you are doing, or would like to do in case of an enhancement idea, and what you would expect to happen.
Don’t be overly verbose, but don’t hesitate to include details that might affect the issue. In Vaadin issues those could be the version of your module, server, dependency injection framework in use, JDK version, operating system, browser (and its version) and so on.
4. Provide a reduced test case
Especially with bug reports, source code is often the best way to explain your issue. If you can provide a clear code snippet that the project maintainers can use to reproduce your problem, there is a much better chance to get it solved. But there are two common extremes that are not too helpful. Either there is not enough code or there is an overdose of it.
If you provide just a line that is throwing an exception in your code, the code sample is often almost useless. For example with Vaadin components, to reproduce an issue, you need some configuration, too, to bring up the issue.
Another extreme is when people attach their whole project to an issue, which usually needs additional setup, like a database connection, to actually run. Another hour to find the view where the problem occurs and potentially it is still hard to debug the issue in your custom environment.
A reduced test case, a code that reproduces your issue minimal code, is the wet dream of all library developers. It is not easy to do for you, but it might be almost impossible for everybody else, and at least will make it faster for others to start working to help you. A good reduced test case will significantly improve the likelihood that a project developer will begin working on your issue next and get it fixed so that it helps you.
To craft a reduced test case, you can begin from your actual project and start removing everything you can from the project: views, dependencies, extra components in your view etc. Simplify to the extreme, but do that in steps, and at each step verify the issue still exists. Sometimes the issue is so complex that the things that actually cause them are surprising. Finally, you can share the project (~ reduced test case) in your forum post or GitHub issue, share it using an online code editor or even provide the reduced test case as a pull request to the project.
In the best scenario, you’ll spot the solution yourself, while reducing the problem. In this case, help others by sharing the solution in the issue you or somebody else created, forum post, blog post or social media.
5. Explain the context
Sometimes all the above is done correctly, but the project developers still wonder what the heck is going on. You might be using the product in a way they have never thought of. You might be using it for something that it is not designed for.
By giving a bit of general information about your use case, you will often get a better answer - faster. Help us to help you to find the right way to use it, to find the right tool for the job and help us to develop a better solution to help you. What is the big picture? What is the original problem you are trying to solve? Are there some special requirements that limit the choices you have?
As an example, I was just recently helping a new Vaadin user to receive data into a Vaadin application. I was doing my best to help him to understand how our Upload component works - until I realized the data was coming in from another service, not from the end user’s computer. The solution was easy when I understood the context: throw in a JAX-RS end-point for the other service and use Vaadin only for the human interface. Vaadin and JAX-RS work fine together. They complement each other in different problems, and they can co-exist in the same web application. But it can be inconspicuous for new (Vaadin) developers, and we should probably highlight this in our documentation. By giving a bit more context in the question, he would have gotten the right answer faster, and I could have used my time to help somebody else.
Start asking for help today!
It is probably a built-in feature in software developers that we try to solve all problems ourselves. We should stop. Good questions educate us, our colleagues and those who answer. Good questions also often lead to innovations and significant development of the project that helps us all. By remembering my five tips, you are not just helping yourself, but participating in OSS projects which help us all.
Got inspired? Head over to Vaadin forums, explain your issue there and toward my attention to it using Twitter. I’ll try to help you with all my knowledge!