Platform Engineering

Everett Toews

Help Others Help You

Posted by Everett Toews on 01 March 2022

culture, people & culture, troubleshooting, debugging

Asking for help is a common and natural thing that everyone does. You need help immediately, so if you can help others help you, everyone wins. Getting help from others is a skill that can be learned and refined over time. This post is geared towards getting help with problems in software development and operations but most of the advice is applicable to many other areas as well.

Rubber duck

Table of Contents

  1. Search for Solutions
  2. Communicate the Problem in Public
  3. Provide Context
  4. Isolate the Problem
  5. Solve the Problem Loudly
  6. Related Work
  7. Conclusion

Search for Solutions

Maybe it goes without saying but starting out by searching for a solution yourself is a must.

Try to find a unique string in any error messages you’re getting and use that as your search terms.

Some targets for your search:

  • source code if it’s available
  • product documentation
  • chat history (Slack/Teams/IRC)
  • good old stackoverflow.com
  • good old google.com

Communicate the Problem in Public

I’m passionate about sharing knowledge. Problem-solving in public is an essential piece of that.

If someone asks me for help as a direct message (DM) in chat, I often reply as below. Please feel free to copy and paste this for your own responses.

Please ask these kinds of questions in a public channel (like #X or #Y) and I’ll answer you there. That way the knowledge is shared widely, more people get on the same page, and it gives others the chance to chip in with answers.

Always encouraging people to ask questions in public normalises the behaviour and works to remove any stigma associated with seeking help publicly. If you need help with something, there’s an excellent chance someone else needs that exact same help. In my opinion, confining the help to DMs hinders the growth of the person and the organisation as a whole.

That’s my general rule of thumb. However, if there are people who will only ask for help in private or not at all then of course go ahead and help them in private. Continue to encourage them to open up for their own benefit and the benefit of everyone else.

And if the same problem requires help time and time again, it’s probably prudent to document it or you can solve the problem permanently with automation!

Provide Context

Providing context is crucial to getting help effectively.

Said in another way, there are no dumb questions but there are incomplete questions. 😉 

What Are You Trying to Achieve?

When someone is trying to help you, understanding what you’re trying to achieve can make all the difference. Sometimes you might be asking a hyper-specific question about a solution you’re attempting but if someone understands what you’re trying to achieve, they can look at the whole problem and potentially suggest a better solution. This is often referred to as the XY Problem.

For example:

  1. Helpee: Why am I getting a ZeroDivisionError when I run my rate function?
  2. Helper: What are you trying to achieve?
  3. Helpee: I’m trying to calculate the rate of water flow in this function in litres/minute.
  4. Helper: Can the time in minutes ever really be zero?
  5. Helpee: Not really …
  6. Helper: Validate the input at the top of the function and return an error message if time <= 0. Please write some unit tests too.
  7. Helpee: Sounds good to me.

The more relevant information you can give them about the whole problem, the better.

Link

Whenever possible, share a link to the exact thing you need help with. Whether it’s source code, logs, or something else. Giving someone a link they can click on to take them to the location of the problem saves so much time and effort. That said, share the link but save them a click and include an excerpt of the logs/code/text in question in chat too.

Link example

Output

When sharing the output of a command, always include the full command (including host info). Knowing the input that generated the output is another huge time saver.

[etoews@jenkins.example.com ~ ]$ ping example.com
PING example.com (93.184.216.34) 56(84) bytes of data.
^C
--- example.com ping statistics ---
4 packets transmitted, 0 received, 100% packet loss, time 2999ms

Code as Code Blocks

When sharing code, always share the code as a code block in your chat tool.

In most chat tools you can start a code block using 3 backticks like so ```.

Resist the temptation to share code as a screenshot, but sometimes there are good reasons to share screenshots too.

Screenshots

If you’re sharing screenshots, annotate the screenshot to be explicit about what you need help with.

Screenshot example

Logs

Logs are usually fundamental to problem-solving. Remember that you can often increase logging verbosity in many systems and tools to get more output. It can be a double-edged sword because it can make it harder to find signals in the noise, but usually, more information is better. And if you’ve increased the logging verbosity in a running system, remember to decrease it after the debugging is done!

Isolate the Problem

Isolating the problem can severely reduce the time it takes to help you.

Let others know what you’ve tried already. That gives them more information and can stop them from chasing a red herring.

If you can reproduce the problem reliably and provide the steps to do so, you are already most of the way to solving it. Those steps will help others get up to speed quickly and get you the help you need. It’s best if you can provide code or commands that can be executed to reproduce it.

Even isolating the problem at a high level can be beneficial. Providing information about whether the problem is in the database, network, API, or some other layer or component can save time.

Solve the Problem Loudly

Others may not be able to help right away but if you keep writing out the debugging steps you’re doing in chat, it can be a big benefit to yourself and others when they do have time to help. In this way, you’re basically rubber duck debugging. You might even be able to solve the problem and be the one who helps whoever comes along next! The more text you provide, the more likely you are to find the issue when searching back through chat history.

Whatever happens, make sure the resolution gets recorded. Don’t leave the debugging thread dangling. There’s a good chance your future self will thank you.

Don’t be afraid to post to stackoverflow.com if you can’t find the answer within your four walls.

Related Work

Conclusion

It’s not always easy asking for help. It’s not always easy giving help. But if you meet in the middle, it can be a huge benefit for everyone – not only to those directly involved but also to those following the chat and searching for answers at a later date.

 

If you like what you read, join our team as we seek to solve wicked problems within Complex Programs, Process Engineering, Integration, Cloud Platforms, DevOps & more!

 

GET IN TOUCH!

Leave a comment on this blog: