Friday 22 January 2016

Write a forum post that can be answered

In the growing world of free open-source software (FOSS) support often comes from online user forums. The quality of those forums can vary in terms of how many people reply to questions but, even in the best of them, a poorly phrased query will not be answered.

I spend a lot of time answering questions on the PsychoPy users forum where users of the PsychoPy stimulus presentation package can get and give help on how to create and improve their experiments. That forum is very active and a lot of people are willing to answer questions.

So why, you might ask, did your question not get an answer? Well, it might be that the timing was bad and everyone was busy, or that you had a great question but nobody knows the answer, but here are some tips to giving your question the best chance of being answered.

The key is that the people answering questions are doing so in their spare time. Most open source software is free and supported by volunteers with day jobs; that's why the software you downloaded was free. Those volunteers are generally willing to answer a question that will only take a few minutes to write. You need to make it easy for them. You need to write something that can be answered and preferably in a short email. Here are some examples of posts that cannot be answered and will typically lead to your question being ignored:
  • I want to use your software but I don't know how. Could somebody give me a working version of what I need? Presumably this will take more than 2 minutes so, unless the software only has 10 users, the answer is "No, it isn't possible for us to create it for you".
  • I created a script but it doesn't work. Any ideas? Could you give us a clue? If I ask you "Why is there no image on my TV?" you wouldn't be able to help me. There are too many possible options. What do you mean by "doesn't work"? What have you tried and what happened (for each option you tried)?
Following your message with "I'm really desperate, can't somebody help me?!! PLEASE?!!!" doesn't help your case. If I can't answer your question then I can't answer your desperate question either.

So, if some questions are not going to get an answer, how do you write a post that will? Partly you need to know how to troubleshoot the software and your script.

Know the basics and use Google first

If you can't use the basic functions of the software yet then you need to start with the documentation or go on a training course. For PsychoPy see the PsychoPy training resouces page. It's fine to announce that you're a "newbie" but implicitly announcing that you haven't looked at the documentation yet will get you ignored.

A huge number of questions have been answered before, and Google is pretty good at finding the previous answers. In particular, you could try using the error message that appeared in your Google search, but simple text of what you aimed to do might work too. Google really is amazing.

Expand on "it doesn't work"

The phrase "it doesn't work" almost never gives enough information. Check your email for that phrase and replace all instances with something more informative. 

What happens when it doesn't work? Does the software crash? Is there an error message? (For PsychoPy) does the stimulus simply not show up? Some people will write "I've tried 4 different ways and none of them worked" but that still doesn't help. What happened for each one?

Explain what is different about your case compared to most others

If you're using software that is popular then in most cases it must be working. If it isn't working in your case then you should think a little about what might be different. Do you have any unusual computer hardware (e.g. a display that's unusually large)? Is the operating system set up in a different way (e.g. you use Urdu whereas most users are using American)?

Does the software provide demos and if so do they work? If none of them work then we could rule out your own coding as the problem. If some of them work then we can narrow down the problem. If they mostly do work then maybe the problem is with your own script.

Are there things that you are doing that are particularly unusual? Are you adding custom code? Are you trying to get unusually short durations for something? Quite often a post on the PsychoPy forum will say that "PsychoPy freezes when I present text" and after several iterations it turns out that the user had written their own custom code for presenting text that used a never-ending loop. Is it possible that your code was the problem, rather than the software?

Anything that you customized needs explaining and probably needs you to paste the precise details (e.g. code).

Don't write too much irrelevant detail

Although you need to provide enough detail for your query to be answered, if you write a really long post with a lot of irrelevant detail, or if you provide your entire 900-line script, nobody will have time to read the post at all.

So, the key is how to give enough detail that it can be answered, and not so much that it will be ignored. What counts as important will differ from one package to the next. For PsychoPy the following are nearly always important:
  • are you using code or Builder to create your study?
  • what version of PsychoPy do you have installed (and have you customised that in any way?)
  • what operating system?
The best way to give just enough, but not too much, detail is to give a minimal working example of the problem. That, ultimately is the aim, but that might warrant a separate blog post.

Just to reiterate, following this advice doesn't mean your question will absolutely get answered. I've seen perfectly good questions go unanswered on the PsychoPy list, often because I (and presumably others) just did not know the answer, or it was going to take a while to work out (sorry!) but the tips above will give you the best chance.