Wednesday, September 20, 2017

How to ask a good programming question

Bioinformatics is full of programming challenges, but did you know that there are people on the Internet right now who are willing to give you programming advice for free? There is just one catch: no one is going to help you if you waste their time. Ever see a painful-to-read question on a help site where the original poster (OP) asks a question, someone responds asking for more information, OP responds with not enough information, someone else responds asking for further clarification, and so on? This is an example a bad question. Time is important to most people, and bad questions waste OP’s time and potential respondents' time. Not many people have the time or patience to go through the effort of deciphering a bad question. On the other hand, a good question will be straight to the point and contain all of the information necessary for someone else to quickly answer the question. Asking a good question makes it much easier for someone to respond since the problem will be clear and example code will be provided. There are five elements to asking a good question, and if you follow these elements, you will drastically increase your chances of receiving a response. However, there is a key point to keep in mind before you ask your question: don't be lazy.

Don't be lazy
In my opinion, the worst type of question is "How do I do xyz?" This type of question is almost never appropriate to ask because it's too broad. When you're soliciting help from a stranger, you need to have a little skin in the game, and this type of question will make it abundantly clear that you haven't put any effort into finding a solution on your own. Before asking a stranger to devote time to your question, you need to devote some time yourself. If you're not sure where to start, then work through a tutorial on xyz, go find a book on xyz, see how people have implemented xyz themselves on GitHub, search StackExchange for questions on xyz, or anything else you can think of to increase your knowledge of xyz. 

You should now be at the point where you’ve tried to implement xyz yourself and you now have a specific question. Keep in mind that you will still need to do some homework (even with a specific question) before posting your question. If you ask a simple question that can easily be Googled, then you might never get a response or you might get a lot of passive aggressive links to LMGTFY. Google can give you a helpful link to documentation or to StackExchange where your question has already been answered. If you’re having trouble finding your specific error or problem with Google, then please see this post for suggestions on how to format your search

The five elements to a good question
Now that you’ve done your due diligence, you can ask your good question. There are five key elements that make up a good question. Follow these to maximize your chances of receiving a response:
  • First, a good question needs a good title that clearly and succinctly conveys the problem. On most sites, only the title of your question will be visible until someone clicks on it, so you better make it straight to the point. An example of a bad title would be "BAM file confusion”, which doesn't specify what the actual problem is, whereas "Trouble calculating average coverage for a BAM file" will make it clear what the issue is. Your title doesn't necessarily have to be in question tense as long as it gets the point across. 
  • Second, have a leading sentence or two about what you're trying to accomplish. Having an idea of the big picture is helpful to others because if gives context to what you’re trying to accomplish. This context might even get you recommendations for shortcuts or alternative approaches that you hadn't considered. After this leading sentence should be the statement of the problem or the asking the question that you’d like answered.
  • Third, include a short, self-contained, correct/compilable example (SSCCE). This is crucially important. Coming up with a SSCCE reduces the number of things that could be going wrong in your code and allows others to quickly reproduce the issue you're having. Most sites allow you to embed code directly into your post, but you can also post your code to a site like Pastebin, which has features like syntax highlighting. Make sure to include sample output, any errors that you get, and other relevant information (operating system, versions of programs/programming languages, etc.). 
  • Fourth, make sure you proofread your post. If you want someone to give you a serious answer, then you want to show that you are serious by using proper punctuation and grammar. Next, ask yourself if your question is clear and straight to the point. Three paragraphs of background before you get to any code means that you aren't being straight to the point. Long, rambling questions like this will cause a lot of TL;DR.
  • Fifth, help others help you. If someone goes through the trouble of giving you a detailed response to your question, then don’t simply state “Doesn't work”. Make sure you specify why it doesn’t work. Make an updated SSCCE with the new code. Are you getting a new error message? Is the output different now?

Where to ask your good question

Now that you know what makes a good question, you will need somewhere to post it. Since a majority of bioinformatics is computer work, StackExchange is a great place to find answers to programming and system administration related questions. The StackExchange communities have a voting system where the best answers rise to the top. This feature makes it very easy to find quality responses to previously asked questions. StackExchange now features a new bioinformatics community for bioinformatics-related questions, but historically a StackExchange-like site, Biostars, has been the place to go for bioinformatics questions. The bioinformatics subreddit has a very active community and it's rare that a good question goes unanswered. Another option is SEQanswers, a popular forum dedicated to bioinformatics and next generation sequencing. Some software developers (like R) maintain mailing lists where you can email in a question which gets disseminated to everyone subscribed. To me, this method is a bit slower than getting help from the above sites, but occasionally obscure bioinformatics software might not be well known on a mainstream site like StackExchange and your only hope for support is via a mailing list. If you're encountering some strange behavior or you think you've run into a bug in a program, then you should consider emailing the developer directly or opening an issue wherever the project’s code repository is hosted (these days, it’s likely to be GitHub).

No comments:

Post a Comment

Popular Posts