Tips to ask better questions

As developers, we all get stuck sometimes. When this happens we start searching for solutions on Google, or we ask questions on Stackoverflow, on the Swift forums, the iOS Developers Slack community or other places. Over the past couple of years, I have been actively trying to help people solve problems they were stuck on and while doing that, I noticed that the art of asking good questions is not an easy one. In today's Quick tip I would like to offer you five tips that I think are important to help you get better at asking questions which will ultimately help you get better answers.

1. Provide context

When you're asking somebody a question, they are often not in the same mindset as you. Whether it's a colleague working on a different feature than you are, or somebody across the world who has never heard of you, or your project, you will need to get them on your page. I have seen people as questions like "Why doesn't my notification fire?" or "How do I fix a layout bug?" and it's really hard to answer questions like these without any context. A brief introduction that explains what you're trying to achieve or what you're working on goes a long way. For example, instead of writing the following question:

Why doesn't my notification fire?

You could write the following:

I'm working on an app that implements recurring local notifications. I have asked the user for notification permissions, and I have confirmed that permissions are granted in Settings but when I try to schedule my notifications, they never seem to be delivered. Any ideas why this might happen?

The latter version of this question provides far more information than the former and anybody who wants to help you is now in the same frame of mind as you are. A little bit of context really goes a long way for anybody who's trying to help you squash that pesky bug you're stuck on.

2. Explain what you have already tried

Far too often have I seen people ask questions that were framed decently, and then discard certain ideas or solutions that are offered because they have already tried those solutions. In programming, there is often more than one way to get from A to B, so when you're stuck on a problem or asking a question, it's really important to share the things you have already tried. This saves the person who's helping you a lot of time because they don't have to type out their ideas if they already know that they won't work for you. Additionally, you might be on the right track with what you've tried, and your problem is related to one of the solutions you've tried rather than the problem you're trying to solve.

Consider a scenario where you're trying to decode a JSON response and you just can't get it to work. If you only ask the following, you're unlikely to get a good answer:

I'm fetching data from the network, and I'm trying to decode this data into a struct. I can get the data just fine but how can I decode the JSON?

After all, you've already tried to decode the response! Instead, you might ask the following:

I'm fetching data from the network, and I'm trying to decode this data into a struct. I can get the data just fine but I can't seem to decode the JSON. I've already tried to write custom coding keys but I'm still seeing decoding errors.

This question still lacks some information which I'll address in my next tip, but the important part here is that anybody who reads this question knows that the person asking this question knows about JSONDecoder and CodingKeys. In other words, they know to put on their helping-you-to-debug-your-JSON-decoding-hats rather than their teaching-you-how-to-decode-JSON-hats.

3. Share your errors

Providing context and some solutions you may have tried is great. But in many cases, anybody who wants to help you still misses a crucial piece of information; the error message. If the person helping you doesn't know what errors you encounter (if any), it's really hard to help you debug a problem. Similarly, if you don't get an error but an unexpected outcome, it's equally important to share the unexpected outcome. Consider the following question:

I'm trying to decode some JSON data into a struct but I'm seeing an error. Any ideas?

Anybody who's willing to help you will follow up with a counter-question:

What's the error?

To streamline the process of getting help, and increasing the quality of potential answers, include the error in your question straight away:

I'm trying to decode some JSON data into a struct but I'm seeing the following error:
Swift.DecodingError.dataCorrupted(Swift.DecodingError.Context(codingPath: [], debugDescription: "The given data was not valid JSON.", underlyingError: Optional(Error Domain=NSCocoaErrorDomain Code=3840 "Invalid value around character 0." UserInfo={NSDebugDescription=Invalid value around character 0.})))
Any ideas?

The person reading this question now immediately knows that your problem is not with the JSON parsing logic. It's with the data you're trying to decode. This is extremely valuable information to have when you're helping somebody. Error messages in the Xcode console often contain crucial bits and pieces of information that point towards the root cause of an issue.

4. Show some code (in text please)

This tip does not always apply, but it often does. If you have an error, question or problem that involves code you have already written, it's very useful to share that code in your question. Keep in mind that whoever is reading your question does not want to go through your whole codebase just to figure out what you're asking. Distill your code to the relevant bits rather than sharing all of your code. Ideally, you would even reproduce your problem with as little code as possible. Sometimes distilling a problem down to the minimum amount of code needed to reveal the problem you have already helps you fix your own problem.

When you share your code, it's okay to replace certain names if you feel like they would give away what you're working on. Just make sure to pick sensible names. Names like Foo, Bar and Baz are common in sample code, but also horrible to read and they confuse the heck out of many people. Also, don't share your code as an image if possible. When you share code, the person who's reading it will often want to copy and paste your code into an editor so they can test it, modify it otherwise try it out somehow. Sharing a screenshot of your code prevents the reader of your question from doing this (essential) experimentation and makes it likely that they decide to not look into your question any further.

5. Get to the point

If you follow all the previous tips, you have a good question. But if you go overboard, you will have a lengthy, wordy question that is buried in details and burdened with background information. When you ask your question, make sure it's easy to read, and as short as possible without omitting any information. Consider the following example:

I was handed a design from our designer and it features some weird user interface components. If you look at the attached image, you'll see a navigation bar, an image, a button, and some text. When I tap the button, the text should fade out and then the next page should appear. The navigation bar should also move up. It's absolutely essential that this works smoothly. How can I handle the button tap and kick off the transition that my designer wrote?

This example might seem like an exaggeration but I have seen questions that were written like this. Instead of writing a question like the one above, something like this is far more valuable:

My designer coded an animation for me and I need to kick off this animation when a button is tapped. I have a function that's called when I tap the button, but I'm not entirely sure how to start the animation inside of this function. I have attached the animation code and my button handler.

The rewritten question is to the point and clearly communicates what you're asking from the reader with just enough detail for them to understand where you're coming from, and where you want to go.

In summary

Asking questions can be hard, especially for people whose first language isn't English. Regardless, I think that the five tips I shared in this article should be very helpful for anybody who asks questions. The more effort you put into writing a good question, the more likely you are to get a good answer, and the quicker you will get to the answer. In some cases, not all five tips can be applied to a question, but I have found that in most cases, you can adopt them in your question one way or the other.

Do you have any extra tips to ask good questions? Or do you have feedback for me? Come find me on Twitter! I love hearing from you.