Effective Troubleshooting

Note: This is a general guide to troubleshooting in general, not about a specific process or program. Most of the advice below is applicable to most processes or programs.

Let’s say you have a problem. You’re getting an error message when trying to carry about a process, or you can’t figure out how to set up a program to work the way you want, or your images don’t look as expected, etc.

Here is a general order of resources to turn to for help:

1. Try to solve the problem yourself.

Before you even start turning to outside resources, try to solve the problem yourself. Just because you’ve received an unexpected outcome doesn’t mean you need outside help.
Some common issues you can solve yourself include:
- Making sure all files and folders are where you expect them to be.
- Making sure all file paths you’re feeding into a process are correct.
- Making sure data copied correctly for one space to another.
- Making sure your code doesn’t have any syntax errors.
- Always make sure to check the small, simple things first.

2. Look at the resources you already have access to.

Always start with what you have close at hand. This could be a software’s user guide, a paper that describes the pipeline you’re running, or even one of the documents within this documentation collective. If you can’t solve a problem yourself, you may already have a resource that can help.

3. Read online guides and forums.

The internet will be a vast and often helpful resource for you.
There are many blog entries, websites, and help guides online on a variety of topics – everything from MRI physics to bash syntax to image registration best practices to general computer issues.
There are also help forums, which are a great resource for programming-centric problems, but other issues as well.
Some helpful hints for effective web searching:
- If you are trying to solve an issue that involves an error message, search for the exact test of the error message.
- Be exact and specific.
- Instead of “how do I set my working directory in python” try “set working directory python3”
- If you don’t initially find what you need on your first search, try varying the detail and word usage in your searches.
- “printer not connecting to computer” maybe not be as effective as “Mac Mojave can’t connect to printer”.
- If you need with specific software, always try the manufacturer’s website first. Many developers also run help forums in addition to including helpful documentation on their websites.
- You can also try searching “[software/process name] forum”.

4. Post on online forums.

You may encounter a scenario in which no resource can help you. This is rare but not unheard of. In this case, you may need to post a question on a forum. Here are some general guidelines for effective forum posting:
But first, Check the forum thoroughly to make sure your question has not already been asked.
Give a concise but descriptive title.
- For example: “Help with matlab problem” is a bad title. It tells the possible respondents nothing about your issue except that it is related to Matlab.
- “How can change colors of histogram in Matlab?” is a much better title.
Contextualize your problem.
- In the body of the post, describe what you were doing when the error occurred, what you expected to happen, and what actually happened.
Add supplementary materials when necessary.
- Most forums allow for adding in-line code or attachments to posts. Problems often become difficult to describe without visual aids. When in doubt, use these.
Be courteous.
- People are more apt to answer a post if they believe the poster appreciates and values their input. It’s always nice to be nice.

5. Ask your colleagues.

Some scenarios facilitate asking colleagues for help, such as when the above steps return no answers or when your questions are about in-house software or lab SOPs
Feel free to reach out to your team members in person, via email, or via MS Teams when need be. And remember that it helps to take a similar approach to the guidelines for posting on online forums.

6. Reach out to authors or developers.

At times it may be necessary to reach out to the authors of a paper, the developers of a software, or the person/people at the heart of the process/software/model/etc for which you are troubleshooting. Don’t be afraid to reach out of this is the case.
Most people are happy to answer your questions if they have the time and capacity to do so. Just remember that this avenue generally takes longer to resolve because individual researchers or small development teams tend to be busy. Be sure to be respectful of people’s time.

Last updated 10 months ago

1. Try to solve the problem yourself.

Before you even start turning to outside resources, try to solve the problem yourself. Just because you’ve received an unexpected outcome doesn’t mean you need outside help.

Some common issues you can solve yourself include:

Making sure all files and folders are where you expect them to be.
Making sure all file paths you’re feeding into a process are correct.
Making sure data copied correctly for one space to another.
Making sure your code doesn’t have any syntax errors.
Always make sure to check the small, simple things first.

3. Read online guides and forums.

The internet will be a vast and often helpful resource for you.

There are many blog entries, websites, and help guides online on a variety of topics – everything from MRI physics to bash syntax to image registration best practices to general computer issues.

There are also help forums, which are a great resource for programming-centric problems, but other issues as well.

Some helpful hints for effective web searching:

If you are trying to solve an issue that involves an error message, search for the exact test of the error message.
Be exact and specific.
Instead of “how do I set my working directory in python” try “set working directory python3”
If you don’t initially find what you need on your first search, try varying the detail and word usage in your searches.
“printer not connecting to computer” maybe not be as effective as “Mac Mojave can’t connect to printer”.
If you need with specific software, always try the manufacturer’s website first. Many developers also run help forums in addition to including helpful documentation on their websites.
You can also try searching “[software/process name] forum”.

4. Post on online forums.

You may encounter a scenario in which no resource can help you. This is rare but not unheard of. In this case, you may need to post a question on a forum. Here are some general guidelines for effective forum posting:

But first, Check the forum thoroughly to make sure your question has not already been asked.

Give a concise but descriptive title.

For example: “Help with matlab problem” is a bad title. It tells the possible respondents nothing about your issue except that it is related to Matlab.
“How can change colors of histogram in Matlab?” is a much better title.

Contextualize your problem.

In the body of the post, describe what you were doing when the error occurred, what you expected to happen, and what actually happened.

Add supplementary materials when necessary.

Most forums allow for adding in-line code or attachments to posts. Problems often become difficult to describe without visual aids. When in doubt, use these.

Be courteous.

People are more apt to answer a post if they believe the poster appreciates and values their input. It’s always nice to be nice.

5. Ask your colleagues.

Some scenarios facilitate asking colleagues for help, such as when the above steps return no answers or when your questions are about in-house software or lab SOPs

Feel free to reach out to your team members in person, via email, or via MS Teams when need be. And remember that it helps to take a similar approach to the guidelines for posting on online forums.

6. Reach out to authors or developers.

At times it may be necessary to reach out to the authors of a paper, the developers of a software, or the person/people at the heart of the process/software/model/etc for which you are troubleshooting. Don’t be afraid to reach out of this is the case.

Most people are happy to answer your questions if they have the time and capacity to do so. Just remember that this avenue generally takes longer to resolve because individual researchers or small development teams tend to be busy. Be sure to be respectful of people’s time.