Help Me, Help You (Debugging Tips Before Seeking Help)

Amara Graham - Apr 23 '19 - - Dev Community

One of the really cool things about being a developer advocate is I get to help people, which I truly love. I love writing a snippet of code or clarifying documentation and then watching the magic that happens when a developer I've probably never met before takes it and creates something amazing with it. That's a great day in my book.

But it is not always like that. Sometimes things break, and folks reach out for help. It can be frustrating for everyone involved when it appears to be "just one error" (it may not be actually!). Let me help you help me as we work through these things together.

Be very clear about your problem or issue

Overstate and overshare. If you can provide relevant screen shots or a link to the code, that's even better.
Was this ever working? Or did you just get started?
What version of the SDK or service are you using? Your OS version might also be relevant.
What steps did you do to get to this point? Link to the exact tutorial or documentation.

Do your homework first

What steps did you take to try to debug this on your own? The answer cannot be "nothing".
Did you do a search on the error? Stack Overflow? Relevant forums? A search engine?
Has this happened before?
Can you try an older version? Can you try a newer version?
Can you reproduce it?

Clouds are complicated

When working in the cloud, you can have a lot more variables at play. I recommend firing off a simple GET to make sure something like your credentials are working and the service is responding. There is a reason many API docs include Curl, but maybe read my other post.
Can you use Curl/Postman/ARC to test the endpoint?
What region are you in?
What tier of the service are you using? You may have hit a tier limit.
Check for outages & maintenance. If you are on IBM Cloud, there is a widget on the dashboard (you may need to be logged in).

Submit an issue (or even a PR)

If you think you are experiencing a bug with an open source project, submit an issue. Often projects will have a template to follow, which look very similar to the items I outlined above! Coincidence, I think not.

Be patient

I cannot drop everything I'm doing to work on troubleshooting, but I try to put some time in my schedule during the week to take a look at things. This is often what you hear from OSS maintainers and can lead to burnout. I don't work weekends or evenings (unless I have very specific events) so I appreciate your patience. Following the above items will help us both tackle these challenges together.


Feel free to apply these things anywhere in life or work. We are all busy, but if we meet each other halfway, everyone benefits.

Do you have any tips I missed? Share them below!

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .