Encouraging Better Questions: Adding Specific Points to "How to Ask" Box

Question

Our current "How to ask" box reads:

How To Ask
Is your question about Arduino?
We prefer questions that can be answered, not just discussed. Provide details. Share your research.
If your question is about this website, ask it on meta instead.
visit the help center »
asking help »

It provides only general guidelines, as does the "asking help" page to which it links. (That page says, e.g., "be specific" without providing much guidance on how to be specific.)

The Dreyfus model of skill acquisition indicates that novices will not be able to well follow general advice and guidelines and instead should be presented with specific things to do; as they increase in expertise they will then be able to start applying more abstract rules and guidelines.

In answering my first couple of dozen questions on this site I've seen some particular recurring patterns with simple fixes, such as poorly formatted code and lack of background information, that made answers more difficult and time-consuming for me. I believe these problems could be mitigated by providing some much more specific direction to novices asking questions. Further, I think that in the course of following this advice novices might be lead to do a bit more research that would make there questions better, though I admit that might be more hopeful thinking than reality.

Should we add more specific advice aimed complete novices and, if so, how should we do it?

Answer 1

I propose we do the following:

1. Create a "Question Checklist" help page (hopefully with a better name) that provides a list of clear, simple and very specific actions that beginners can take to improve their questions. (See below for my initial go at this.)
2. Change the "How to ask box" to add, "Review the question checklist page before posting your question and ensure you've fixed all applicable issues."
3. Change the Asking page in the help center to say, at the top, "Before pressing the post button go through the question checklist page to see if there are any easy improvements from that list you can make. This will increase the chance of your question getting a response."

Here are some things I think should be on the checklist:

• Have you been following a guide or other documentation? If so, provide a link to it.
• Do you talk about a specific Arduino board? If so, provide a link to a product page for that board.
• Do you have a specific device attached to your Arduino, such as a sensor or network interface? If so, provide a link to the datasheet for that device or the chip on it. If you can't find the datasheet, at least provide a link to a product page.
• Are you calling code in a library? If so, include a link to the documentation for that library (perhaps one of these, perhaps something from elsewhere).
• Have you included code in your post? If so, make sure that it's nicely formatted to be easily readable.
• Do you have more than 20 lines of code in your post? If so, remove extra functionality that you can remove that still leaves the problem behind (i.e., the remaining code still demonstrates the problem you're having). Make sure you test your new, smaller code to confirm it still demonstrates the problem.

(The "nicely formatted" item needs improving; we should provide specific direction on how to run it through a code formatter.)