Years ago in my Linux studies I discovered Eric S. Raymond’s advice on asking technical questions entitled “How To Ask Questions The Smart Way”.
This advice was tailored within the context of an Open Source enthusiast who often seeks out help from other people with similar interests.
I wanted to create a short, customized version of this advice tailoring it to something I can can quickly share with with someone who is having trouble articulating a problem and its context with a quick checklist:
1. Use Google. This is obvious but double check you understand how to make smart, efficient searches
and try several different phrases including using
- to exclude terms and
"<term1> <term2>" to group them together
(see Google Advance Search or
read this lifehack.org article).
2. Be precise and informative about your problem
- Describe exactly what you did (if a command-line or script error, include full command-line and output)
- Describe the environment it occurs in:
- On what server?
- As what user?
- From what current working directory?
- Any set-up steps required
- If possible, provide a way to reproduce the problem
- Describe any research you did trying to solve the problem
- Describe any diagnostic steps you took to try and pin down the problem yourself
- Do the best to anticipate follow-up questions that might be asked
3. Describe the goal, not the step. Often, people who need technical help have a high-level goal in mind and get stuck on what they think is one particular path towards the goal. They come for help with the step, but don’t realize that the path is wrong.
- Bad: “How do I get the color-picker on the FooDraw program to take a hexadecimal RGB value?”
- Good: “I’m trying to replace the color table on an image with values of my choosing. Right now the only way I can see to do this is by editing each table slot, but I can’t get FooDraw’s color picker to take a hexadecimal RGB value.”
4. If you figure out the answer yourself after asking, follow up with a brief note on the solution or at least that its fixed.
- If you figure it out yourself, share the solution with whom you previously asked.
- If you were provided a solution, give feedback especially if the solution works.
- In both cases, if you asked for help, the person helping might continue spending time researching because they didn’t know your problem was solved.