How to ask help for technical problems?

Oct 28th, 2020

by Juha-Matti Santala

This was published in categories: javascript rust python

Over the years, I've been involved in a lot of different groups and communities where people ask for help for technical problems. I've seen some great questions and some where even just getting to the actual problem has taken a long time.

In this post, I want to give some tips for anyone who wants to get help with their problems because the better your question covers different things and explains the problem and what you've done, easier it is for someone to help you. I do want to emphasise that for beginners, it's not easy to ask questions because there's so many unknowns. Hopefully these tips will help you on your journey to seek knowledge.

Most of these are meant for asynchronous communication like chat apps or forums or sites like Stack Overflow and focuses on programming related questions to narrow the scope of the post.

The common thread in all these is to provide as much information and being as specific as possible up front so you and your helpers don't have to spend a day going back and forth before getting into the actual problem.

1. Ask your question, don't ask if someone can help

Let's start with the first message you send. I often see people start by asking "Is there anyone who can help me with XYZ?".

It sounds reasonable, right? However, it can hinder your ability to gain help a lot:

It's hard for the helper to know if they can help
It lengthens the discussion loop unnecessarily long

Let's say you are struggling with something in CSS. If you post a message on a proper chat room (like developer communities in Discord or Slack), there might be a lot of people who know CSS but they might not know the exact thing you're struggling with.

Second, by asking that requires someone to say "Yes, what's your problem?" and it may take a day to even get into the discussion of the problem itself.

Instead, just ask your question directly. "I'm trying to center align a div inside another div but can't figure out how?" is a much better start. We'll learn how to make it even better later in this post.

When you ask the question like that, anyone at any point can take a look at it and have a better idea about if they can help you and they can start answering right away. You might get a solution to your problem even before you return to read the chat for the next time.

2. Explain what you are trying to achieve

It might sound obvious but very often it's missing and can lead the people helping into a wild goose hunt to the wrong direction. This is especially relevant with new developers because you might be trying to do something with a bit wrong set of technical tools.

The more specific you can be here also helps people grasp what you're aiming to do which helps them give you better answers.

Rather than focusing on the technical implementation details, focus on what you want the effect of the code to be.

This is also known as XY Problem.

3. Include example input and output data

If you're working on something that takes in data and outputs something else, provide both an example set of data to be used as an input and an expected output. Even better if you can provide multiple sets of different input/output pairs so your helper can test out that their implementation of the fix actually answers to your question.

For example, if you're working on some regex or validation with Joi, offering a test input helps a long way in reducing back-and-forth between you and your helper.

"My code doesn't work, why?" isn't very helpful but often encountered question. The answer to that often is "I have no idea".

So instead of being vague, be as specific as possible. One way to be specific is to share the error code you get (and share it every time when it changes during your process of figuring it out). For an experienced developer, errors reveal a lot so sometimes just looking at the error alone we might be able to figure out the problem – especially if it's a very common one.

And please, always share those as copy-paste into code blocks (see next section for those) because that allows us to copy-paste further and search from Google if it's something we're unfamiliar with. Screenshots of errors are often just one more hinderance in trying to figure things out.

If you're using some specific applications or libraries, share version numbers of those. For example, if you have a problem with Django, please tell the version of Django and version of Python that you're running. Programming languages and tools evolve and it might be that it's a specific issue to your version.

5. Show your code

It's very important to show what you have tried to do for a couple of reasons.

First, it's more motivating for someone to help you when they know you're not just asking someone to do the work for you but that you've actually tried solving the issue yourself and are genuinely stuck.

As someone who teaches a lot, I try to avoid giving direct answers as much as possible and rather try to help people learn how to figure it out themselves and how to find the right information. That's impossible if you're only looking for direct complete answers.

Secondly, it can be really difficult to give programming advice to a specific problem if the person giving advice doesn't know what your code looks like. This is especially important when you have an error or something's functioning incorrectly.

There are different ways to share the code. For HTML/CSS/Javascript stuff, you can use Codepen or for more complex frontend code, use Codesandbox. The big benefit of these two is that you can run the code and see the result. Most problems are not solved by staring at the code and returning the answer but often require some tinkering and these platforms are great for that.

For other code, there are tools like Pastebin which allow you to paste anything, choose a syntax highlight and click submit. Or if your code is short, you can send it directly in Discord/Slack. For that, here are couple of tricks to make it easier for your helper to help you:

To share code in these platforms, wrap it around three backticks:

```
your code here
```

On Discord, you can also add a language definition after the first three ticks to add syntax highlighting:

```js
// javascript code here gets highlighted
```

On Slack, you can create a code snippet from the lightning menu which allows you to add syntax highlighting:

Slack's Code Snippet modal with example Python code — (thanks Juri for pointing this feature out)

Reading code that is not shared inside these code blocks (created by triple backticks) is very difficult to read.

6. Create a Minimal, Complete, Reproducible Example

Codebases are often large and complex and it's not beneficial to share all your code that exists.

Quoting from a great instruction post in Stack Overflow:

Your code examples should be…

…Minimal – Use as little code as possible that still produces the same problem

…Complete – Provide all parts someone else needs to reproduce your problem in the question itself

…Reproducible – Test the code you're about to provide to make sure it reproduces the problem

I won't copy or rephrase everything from that post but rather advice you to read it with thought.

This is one of those things where I think we need to be most lenient, especially with new developers. If you're new to software development and your code doesn't work, it's very likely you don't know why (that's why you're asking, after all) and it can be very difficult to create an example like that.

But reading it through and understanding why it's a positive thing to thrive towards can help you a long way.

How to provide help

Ned Batchelder has written a great article on the other side of the table: how to help when asked.

I won't repeat the points here, I recommend reading through his post. I do want to emphasise the sense of empathy and humility that comes through from his advice. Asking help from someone - strangers or friends - puts the asker into a vulnerable position and we can do so much to help not only with the technical problems but with the experience of asking and receiving help.

Wrap-up

A good question is a combination of all the above: asking directly to get things started, stating what you're aiming to achieve, sharing the errors you're encountering, sharing the code is causing you these problems and making the shared examples minimal, complete and reproducible.

By putting these advice into work, I can guarantee that your experience with seeking help will get much better. A side effect might be that you get less discussion going (less people asking for more info) but you also save your and other people's time when they don't have to ask a lot of things only to find out that they cannot help you that time.

And finally, remember to say thanks when you get help. I didn't add it as its own point since I've never had the issue of people not saying thanks. But if you have gotten help and didn't say thanks – do so in the future.

I know asking help can be a daunting task: exposing your imperfection to strangers can be scary. Despite making this long list of things you should do, I do want to encourage you to ask even if you are not perfect in all of these. This post is aimed mainly to provide you with some new ideas that you might not have thought about or known about.

I wish you get help for your technical problems!

(PS. If you're an experienced developer, you might notice that all of these translate very nicely into writing good bug reports. That's because a bug report is essentially asking for help in fixing something.)