How to write a help request

Most of the help requests we receive don't provide enough info, and we have to write back asking for more, sometimes several times, before we have enough info to help. To get your question answered quickly, please review these guidelines.

When you ask a software developer for help, consider the way you would ask a mechanic or a doctor for help. Like your car or your body, software is a complex system whose inner workings are not visible; but an experienced professional can diagnose the problem if you clearly describe its outward symptoms.

The universal formula to ask for help has three parts:

  1. What you did
  2. What happened when you did it
  3. What you expected to happen instead

You can omit step 3 if it's obvious from step 2. For example, if the app crashed, it's obvious that you expected the app not to crash. But a document appears with white text on a black background and you expected it to appear with black text on a white background, you should say that.

Now let's look at how to write steps 1 and 2 effectively.

What you did

This should be a list of actions you took before the problem occurred. For example, you might tell an auto mechanic that you shifted into reverse, then turned the steering wheel all the way to the left, then pressed gently on the accelerator. Similarly, you might tell a software developer that you clicked the Login button in the top toolbar, entered your username and password, then clicked the Submit button. You should always use the exact names of the elements you are working with, or describe their icons if they don't show a name.

Here are some examples of how to say what you did before a problem occurred:

Don't say: I tried to copy a layout
Do say: I clicked the Layouts button in the top toolbar, then clicked the Copy button in the popup menu.

Don't say: I opened a document
Do say: I clicked the Repertoire button, then the Documents button, then I clicked the document icon next to the "Freebird" document

Don't say: I'm sending program changes to my keyboard
Do say: I connected my keyboard with an iRig MIDI interface, then I clicked Songs in the main menu, and clicked the MIDI icon next to the "Freebird" song

What happened when you did it

This should be a detailed description of what you saw when the problem occurred. For example, you might tell a doctor that your cheeks turned red and you felt dizzy. Similarly, you might tell a software developer that a progress bar appeared in the center of your screen and didn't go away after waiting five minutes. Like the old Dragnet TV show, this should include "just the facts," not your interpretation of what happened.

Here are some examples of how to say what happened when a problem occurred:

Don't say: The app crashed
Do say: The app disappeared and the home screen appeared

Don't say: My MIDI messages won't send
Do say: The lights on my MIDI interface didn't blink and my keyboard remained on the current program

Don't say: The audio playback doesn't work
Do say: The speaker icon changed from white to gray and I didn't hear any sound

Don't say: I got an error message
Do say: An error message ending with code 320 appeared on my screen

Additonal tips

  • Including a specific example (when I click the Edit button for "Freebird"...) is always better than a blanket statement (when I click the Edit button for a song...).
  • A picture tells a thousand words: if a problem is visual in nature, you can send a screen shot or even a video showing the problem. But these should supplement, not replace, your written description.
  • Beware of these phrases: "I tried to…" should be replaced with a description of what steps you took. "I couldn't…" and "…didn't work" should be replaced with a description of what happened.
  • If you are not fluent in English, you should still try to follow these guidelines. In this case, it's even more important to include lots of details, because if we don't understand a part of your message, we might get what we need from another part.