GREAT questions
For both filing bugs and asking questions of engineers, the trick is to make it easy for them to help you with your real goal and to show your respect for them.
Fortunately, there is a simple mneumonic that works for most situations — ask “GREAT” questions:
- Goal
- Repro
- Expected behavior
- Actual behavior
- What you tried on your own
Start with your high level goal
This helps avoid the XY Problem, where you think you needed help on a specific solution X to your problem Y, but X wasn’t even the best solution.
- “I’d like to center this image vertically on the page and have text flow around it”
- “I’m trying to shrink the size of this video file as I import it from my camera’s SD card”
Give minimized and explicit steps to reproduce your confusion / issue:
- “I am setting the margin-top on the image to be …. Here is a minimal html file that shows what I’m trying to do”
- “I am using ffmpeg. Here is the actual command line invocation I’m using: …”
Explain your mental model, what you expect to happen
- “I’m expecting it to tell it not to put other images in the margin of my image but allow text to be near the image”
- “I’m expecting it to read the image off the microsd card and write it to my home folder”
Show them what actually happens
Include exact error message or screenshot/details of failure. Show, not tell.
- “Unfortunately, it ends up aligning just being put below all my other text content”
- “Unfortunately, I get this error: ‘…’”
Show what you tried on your own
This is a critical step! This is the “proof of work.”
- “I found this stackoverflow article which looks related. I re-ran ffmpeg with DEBUG=1 and got the following message, which was different than what I expected: …”
Ask a question, referring back to your high level goal
Do you have any ideas about what I could be missing? Or other suggestions for how to get the image centered on the page?
Other tips
- Have a detailed summary (e.g. in the subject of an email or a title of a question)
- Don’t ask to ask
- When you thank them in advance for helping you, explain why you asked them in particular.