How to Ask for Help

Asking for help is a skill in and of itself. It takes practice and a bit of effort, but the payoff is significant. The benefit is usually very quick, concise answers and the penalty a lot of frustration mired down in vague discourse. . . not to mention wasted time that could be spent on much cooler efforts, like youtube.

When to Ask

Probably the most important part of asking a question is knowing when to ask. It's good to take several steps before asking a question. It will help you form your question more intelligently and thoroughly which usually leads to a quicker, more accurate answer. These steps often lead to a solution in very short order preempting the need to even ask a question.

1. Read the help files.
   1. Help files are often very helpful. It sounds amusingly redundant if said out loud, but it's very true. Often in our rush to find an answer, we forget the most obvious place of all. If a program isn't acting the way you think it should, that's a great time to read the help files, manual, etc. If your new to Unix, you might want to glance at some of the external links below, particular How To Read a Man Page
   2. Many programs have a built in quick help. This is normally accessed by using the --help or -h switch (usually both) or is output in addition to an error. For a program named "foo", you would: $ foo --help or $ foo -h. They often use the same syntax as man pages, so reading the Man Page How To will make it clear.
2. Search any pertinent mailing lists and see if someone else has addressed the issue and resolved it
   1. Mailing lists are where people go for help. If your problem is a common one, you can often find the answer on a mailing list. It's also a great place to ask for help if you cannot find a post covering your specific issue
3. Search in Google
   1. Google is an amazing tool. It's virtually guaranteed that your not alone in your problem and many people post the solutions they've found. Often something as simple as cutting and pasting your error into Google can bring you right to the solution.
4. If you've done steps 1, 2, and 3 and couldn't find an answer, it's time to ask for help.

Asking the Question

The good news is that now your probably well prepared to form an informed, clear question. Below are the components of a good question that will help the person help you:

1. What did you find out from using the Help Files?
2. Did google provide any insight?
3. How did you attempt to solve the problem? What were the results?
4. Did the program/method/script used to work? Are you aware of anything that's changed since then?
5. Include a description of your Operating System. Include: OS Version, Terminal program (X11 or Terminal.app?), Program name and version.
6. An example command that produces the problem and a clear statement of expected outcome versus actual outcome.
7. Copy and paste of the error output including logs. Without these there's no way for the person helping you to know what's going on. TIP: For finding FSL logs please see Finding FSL Debug Info
8. If relevant, a step by step walk through of what leads to the problem and how to reproduce it consistently. Include example files, paths, and all relevant information.

Example of a Well Formed Question

I've been experiencing a problem with foo.

Environment: - OSX Leopared - Terminal.app - /usr/bin/foo version 3.5

Error Description

$ foo /Volumes/home/me/myfile.input /Volumes/home/me/myfile.output

Expected Output After completion, myfile.output contains a list of pertinent statistics.

Actual Output

!! myfile.input has greatly offended Foo !!

Log output The myfile.out.log found at /Volumes/home/me/myfile.out.log contains an additional error, though I'm not sure what it means:

file bar produced bah with error code -2179

The man page seems to indicate this is the appropriate syntax: $ man foo => foo: a program that bar's a file => foo <infile> <outfile>

The man page also says that infile has to be a bar type file. I'm sure that myfile.input is a bar file. I googled the error output and someone suggested that foo only takes bar type 1 files and fails with bar type 2 files. So I made sure that myfile.input is, in fact, a bar type 1. Still no go.

Work Flow

• From my local machine:

$ ssh me@someserver.com
Welcome to someserver!

• In someserver.com

$ /usr/bin/foo /Volumes/home/me/myfile.input /Volumes/home/me/myfile.output
!! myfile.input has greatly offended Foo !!

Any help is much appreciated.

-me

General Trouble Shooting Tips

Test with more than one set of data

For example, if you're getting errors with a specific image, try another one. Preferably one from a completely different batch. If the other set of data works, it is a good indication that the problem is specific to the data set you're dealing with. Make sure to include all such examples in your final help request.

Test with more than one account

If you are seeing a problem with a particular program, verify with others whether the same program works as expected for them. If it does, this is a good indication that the issue lies in your user specific environment.

If possible, test on more than one machine using the same data set

This will determine whether the issue is specific to that particular install of the program.

References

Finding FSL Debug Info

External links

• How To Read a Man Page