How To Ask for Help

There is a curious phenomenon in programming where a beginner will ask for help as if you can read their code on their computer, and their mind, and the screen. I will get a question that is one sentence, no code samples, no screenshots, no photos, nothing except for a single line like this:

From: student@university.com
To: Zed
Subject: Help

"Hi, my code doesn't run something about syntax error?"

I like to call these kinds of questions "psychic teacher questions" because they seem to assume that the teacher is somehow a psychic and can see through their brain and onto their computer. I personally find this fascinating and I may write another blog post about why I think this happens, but in this blog post I'm simply going to tell you how to avoid asking questions like this and how to get help from a more experienced programmer without embarassing yourself. At the end of this essay you'll have a consistent process for writing an email that will get you help, but will also help you figure out your problem on your own probably 60 to 80% of the time.

Don't Be A Toddler

If you are the type of person who asks these psychic one-liner questions, then you should know that it annoys nearly everyone who receives them. Most of us will try to be polite and ask you follow-up questions, but this style of beginner question really is a waste of everyone's time. Mine and yours.

If you were four years old I would understand why you think I can see your screen. A toddler's brain simply isn't developed enough to understand that I don't see what they see. You, however, are most likely at least over the age of 12, so why do you assume I can see your screen and your code? Just in case it's not clear, I cannot see your code, your screen, your thoughts, your feelings, or anything else about you. As an adult--or near adult--you have to take the time to communicate those thing clearly to me.

You are effectively asking for help like a toddler, and you need to learn how to ask like an adult.

How To Get Help Like an Adult

The key to this process is to understand that you don't have to know everything about the problem, you just have to know as much as you can about what you have been doing. This seems like a strange shift in perspective but what it will do is help you figure out how you are seeing things so you can explain what you see and what you experience to someone else. A bad student question is one where you assume the teacher is psychic and they don't need any information to help you. The way to avoid asking these questions is to go through a process that helps you understand what you actually know about the problem yourself.

As you go through this process keep in mind that it is mostly a guide. There may be parts of this process that don't fit with the kind of problem you have so feel free to modify it and change it up keeping in mind the final goal is understanding what you already know and to view your problem in a new light.

Step 0. Google The Error

Before you do anything, you should use Google for the error message. You wouldn't believe how many times all I do for students is take a piece of their message, put it into Google, and paste them back the top link. When I worked as a consultant I joked that I was basically paid to Google things for people. If you do search for the error message, try to keep the snippets small and remove any random numbers or things specific to your computer. Usually you can just search for a few of the key unique words within the error message and you'll get quite a few useful results. Watch out for old information. Sometimes you'll find something that looks like an answer, but check the date above to make sure it's not too old.

Step 1. Email Yourself

The very first thing you should do when you have a problem and you want to email somebody, is to first write yourself that email. It may seem strange but it actually works very well. You wouldn't believe how many times I've received an email asking for help, and then two hours later received an email saying, "oh hey I just figured that out." It seems the simple act of sending an email with your thoughts articulated in the email helps you figure out what is possibly wrong. I don't know why this is but there are many debugging and analysis methods that use this phenomenon to figure out complicated problems.

This will also help you practice writing an email for the remaining steps so you know your email is good before send it to someone more experienced.

Step 2. Attach Your Code

I cannot stress this enough! You must attach your code or at least paste the relevant part of your code to the email. If your code is a mess, then it might be worth it for you to clean it up and simplify it before sending it. In fact, sometimes cleaning up the code and preparing it to send helps you find the bug. Without the code it may be possible to help you, but with the code I am much more inclined to take a quick look and possibly find the error.

Remember, attach your code as a file, don't copy-paste it directly into the email. My email client will mangle the code making it harder to read.

Step 3. Take Screenshots

If your problem results in some kind of photographic error, or if it shows up in your terminal program and it's too difficult to paste it reliably, then you need to take a screenshot. The easiest way to take a screenshot is to use the operating system's default screenshot method.

On OS X you hold down shift–command–4 then select the region of the screen you want to copy.

On Windows it changes constantly but usually I just hit the window key, search for "snapshot", and then use the Microsoft program that lets you do this. I believe currently it's called snipping tool but in the future it's going to change to something else and most likely will change again and then again and then again.

On Linux it depends on the desktop interface you are using. I tend to say that Linux users deserve their user interface so it's up to you to figure out how to get a screenshot.

I'm a huge fan of a tool called LICEcap. This tiny little cross-platform tool does small GIF videos of your screen. LICECap is best for super short, 4 frames per second (fps) videos that show some interactive problem. If what you want to show is not moving then do a normal screenshot.

To use LICEcap you simply expanded out to the section of screen you want to record, set your frame rate to about 4 fps, and then hit record and click through the Window pretending to click into your own window. It's very fast and simple and when you're done you have a tiny little screenshot that you can upload to Twitter, Facebook, Instagram or send an attachment if it's small enough.

In general if your attachment is larger than 1 MB you shouldn't send it as an email attachment. Use a service like Google Drive, Dropbox, or whatever Microsoft's competitor of the week is.

Step 4. Show Your Errors

I shouldn't have to say specifically "show your errors" but it seems that people don't understand that the exact specific error message is required. You cannot paraphrase it or quoted from memory or anything like that. You must actually grab a screenshot, copy-paste, or use LICEcap and send it.

One reason beginners have problems with error messages in programming is that the error messages have information that you think is not important but actually is. You will focus on something that is actually irrelevant and send that, but then one line above what you just sent is the real error location. To stay safe just send the whole error message, but within reason. If your error output is gigantic then you want to attach it as a file or put it online for people to look at.

Step 5. Explain What You Did

Your first email to yourself now has attachments of source code, screenshots, and error messages. make sure these attachments have meaningful names so you can actually reference them in the email you write next.

Now you begin to describe how you got in this situation in the first place.

If the problem you're describing is some bug in software you use (rather than a programming mistake you made), then you should try to explain the steps you took to get to there in as clear a way as you can. It can help actually to simply record yourself doing it with something like OBS, and then either send that video or watch it to see what you did.

If the problem is a programming problem you may not have the steps in your mind for how you got there. In that case you explain what you were doing in the programming environment before this happened. For example, you may say, "I was trying to make this one function shorter and you got this error." Or you may say, "I was trying to do exercise 4 of your book and I got this error."

For programming language error messages it is very important to reference line numbers when talking about your code. When you are describing the steps you take to cause an error, don't say, "When I change that variable I get this syntax error." You have to be specific and say, "When I change the variable named apple on line 27 I get this syntax error in the attached file error.txt."

Step 6. Explain What You Expect

The next step is to explain what you expect should happen. Your problem could just be a misunderstanding. If you explicitly state what you think should happen, then it's easy to figure out if this is just a misunderstanding or if it's an actual problem. As with explaining what you did, it's important to be very specific so if you aren't clear about what your expectations are then you need to sort that out and get it into writing.

For example, you can't just say, "I thought it would just work?" What you actually need to say is, "I thought changing the variable apple to the number 4 would make the loop go 4 times but instead it went 5 times." That will make it much easier to figure out if what you're thinking is correct and then how to fix it.

This part of your email may not apply if your problem is more that you just messed up your code when trying to do something. In general what you expect to happen when making changes to your code is that it works, but it may still help to write out what you thought should have happened after you were done making your changes.

I think it's also important to list why you think it should happen this way. You may even figure out what your problem is on your own if you start asking yourself why you think things work the way they do.

Step 7. Guess At Causes

Your next next task is to guess at what is possibly causing this unexpected result. This should simply be an enumerated list of things that could be going wrong. Keep each description of possible problems short, and include the things that you've already tried to fix because in the next part you're actually going to list what you've already tried.

Pro-Tip A very common mistake I see beginners make is they only look at one line of code and not anywhere else in their code. You'll read an error message that says 14: Uncaught ReferenceError: x is not defined, go to line 14 and stay there for the rest of your life. All error line reports are only the location that the programming language finally figured out something is wrong. Programming languages are notoriously terrible at giving exact locations of errors. You must start with the line reported, then work your way backwards and check all the lines before that line.

That means, if you get an error for line 14, you look at 14, 13, 12, 10, and so on until you've looked at every line.

Step 8. List What You've Tried So Far

Once you have your list of possible causes, you should then list what you've already tried as possible solutions to those causes. You don't have to try to solve everything on the possible causes list, but it's important to list what you did try so that the person helping you either doesn't try those things too, or tries a more sophisticated version of the same thing.

This also has the effect of showing the person helping you that you are actually doing your own work. People are much more inclined to help you if they see that you are actually putting in work to fix the problem on your own and only need a little help to finally solve it.

Step 9. List Your Gear

In a corporate environment you may not need to list your equipment since everyone may be using the same equipment. In that case you can simply say what is different about your equipment compared to everyone else. This is especially important if the error you have is network related, and you have somehow disabled or enabled some kind of security measure. Your problem might be that you removed some driver, installed an antivirus, removed an antivirus, or did something that caused your computer to malfunction inside the corporate network.

Pro-Tip Also always check your cables are plugged in before you ask for help with the network.

In every other situation you should list out the basics of your computer such as the operating system, the browser, text editor you're using, version of your programming language, and possibly any antivirus or strange situations regarding your software.

Pro-Tip I personally find a really nice short OBS video generally shows me everything I need to know about a person's computer. Consider complicated problems might be better as a video then an email, but still take the time to write this email so that way when you create your video you don't fumble around trying to explain what's going on.

Step 10. Send and Go Relax

You are ready to send your email. You have your code attached, relevant screenshots, and all the information you can think of in the email. You now should send it to yourself and then go to sleep.

You don't have to go take a nap but go take a walk, take a break, play video games, eat, shower, anything but sit there in front of the computer. There is a certain kind of magic when you describe a problem you've been having with code then send it off into the Internet even to yourself, and then take a break and stop thinking about it for a few hours. For some reason your brain keeps working on the problem but now it has new information and a new perspective. If you go to sleep you may even have strange dreams about the error and you might even wake up in the middle of the night with the solution.

If after your break you haven't had any significant clues or ideas, then go back to your email open it back up, and resend it to your instructor (or whatever you call the person helping you). At that point you have probably given them enough information and proven that you've worked hard enough that they will not mind helping you.

A Note for Corporate Situations

If you're in an environment where you work at a corporate office you may not want to send an email. It's up to you to figure out if your culture is one where people prefer emails when being asked for help or if most likely they will just ignore your email because they ignore all of their email.

You should still send yourself that email even if nobody else likes receiving email. You can then use this your self email to show them what you've been doing to solve the problem and help them help you.

If they do mind helping you in this situation I would suggest possibly finding another person to help you or maybe even finding someone outside your company who will help you.

Conclusion

Hopefully you have a decent guide for asking for help as a new programmer. You may have other programmers give you other advice so take into account what they want when they ask for help, but in general if you provide all of this information they should be fine with it. If they aren't fine with it, then consider asking somebody else for help.

More from Learn Code the Hard Way