"My code doesn't work"
"Help"
"How to do [insert vague concept]?"
"How to fix this issue?"
"Why doesn't my code work?"
"Help me fix this [add error screenshot]"
You've probably encountered a variation of these questions many times in your career.
I certainly did. I worked as a developer and a developer advocate in companies with big, active communities, and my role involved providing support to developers.
After interacting with so many developers, I realised they have a problem with communication. More specifically, they don't know how to ask for help. Then, they get frustrated they don't receive help.
But they forget something - you need to help others help you! In this article, you'll learn how to do that.
0. Describe the issue
It's not enough to say "my app doesn't work" or "can't start the project locally" or any other vague statement like this. People can't magically guess stuff such as:
- what the errors are
- what caused them
- what is your environment (operating system, programming language, tool version, etc.)
- what are you trying to achieve
When seeking help, try to provide as much context as possible because people have zero knowledge of your problem. The more context & details you provide, the easier you make it for people to help you.
So, instead of saying "can't run the project locally", you could phrase it as follows:
Hey! I cloned the project and tried to run it locally on my Macbook. I added all the required environment variables and started the required Docker containers: mailbox and database. The node version is v20, and the npm version is v8. However, when I ran "npm run dev", I got an error saying, "npm ERR! missing script: dev".
The difference between the two phrases is enormous. With the former phrase, there would be a lot of back and forth between you and someone trying to help you.
The second phrase provides a whole lot more context, and therefore, it increases your chances of getting help.
So, always make sure to provide as much context as possible.
1. Explain how to reproduce
Sometimes, describing the issue is not enough. In those cases, people might have to reproduce it on their machine to get a better understanding and be able to help.
So, providing all the steps required to reproduce it is important. Once again, it's helpful to be as explicit as possible.
Mention:
- all the steps required to get the error
- the tools/technologies you used and their version (if applicable)
- the configuration required (e.g. setting environment variables, changing flags, etc.)
Let's use the previous example to show how you can explain how to reproduce the issue.
Hey! I cloned the project and tried to run it locally on my Macbook. I added all the required environment variables and started the required Docker containers: mailbox and database. The node version is v20, and the npm version is v8. However, when I ran "npm run dev", I got an error saying "npm ERR! missing script: dev".
Steps to reproduce:
- Go to https://github.com/user/repo
- Clone it to your machine
- Create an env file and add the required env vars (next_public, db_host, and secret)
- Run npm install (you'll need node@v18 and npm@v7)
- Run npm run dev
Anyone can now reproduce the issue. If you didn't provide the steps, people would have to guess and be less likely to help.
Remember, you want to remove as much guesswork as possible for the person trying to help you.
2. Try to solve the problem yourself first
This one might seem like an obvious one. But it's not.
It's surprising how many developers reach out for help immediately without trying to solve the problem themselves. They bypass an essential step in software development - debugging.
But debugging is a core part of software development. You have to do it whether you like it or not. Although frustrating at times, debugging is a great way to improve your skills and better understand the code you're working with.
We won't go in-depth about the benefits of debugging, but some of the benefits are:
- it improves your problem-solving skills
- it helps you understand the code better
- it helps you learn from your mistakes and errors
Moreover, asking for help without trying to solve the problem is a sign of disrespect for other people's time. It can come across as taking other people's time for granted and using them to do the work for you. No one likes that.
Continuing to do that only strains the relationship with your workers, friends, or community members, and your future questions will most likely be ignored.
So, always solve the problem yourself first.
3. Show your solutions
After trying to solve the problem yourself, note what you've tried and achieved.
This includes any changes made to your code, adjustments to your configuration (like changing environment variables, app flags, etc), online solutions you've followed, and so on. Add anything that could be useful for people to get context.
When you reach for help, include these solutions so people can see what you've tried. They can avoid wasting time on something that doesn't work, and they can try other solutions. It also shows that you're proactive about finding a solution and that you respect their time.
Here's how you could modify the previous example to include your solutions:
Hey! I cloned the project and tried to run it locally on my Macbook. I added all the required environment variables and started the required Docker containers: mailbox and database. The node version is v20, and the npm version is v8. However, when I ran "npm run dev", I got an error saying "npm ERR! missing script: dev".
Steps to reproduce:
- Go to https://github.com/user/repo
- Clone it to your machine
- Create an env file and add the required env vars (next_public, db_host, and secret)
- Run npm install (you'll need node@v18 and npm@v7)
- Run npm run dev
So far, I've tried the following solutions:
- Checked the npm scripts in "package.json" to ensure "dev" is actually defined. It's there, and it still doesn't work.
- Tried running "npm install" again to make sure all dependencies are up to date. No luck. Same error.
- Googled this error message and tried a few suggested fixes, like deleting the "node_modules" folder and reinstalling everything.
So, always include what you've tried so far to solve the problem!
4. Add supporting material
Adding supporting material such as code snippets, screen recordings, screenshots, and gist links where appropriate is also super valuable.
Visuals like recordings and screenshots provide additional context. They show the whole "picture", which might contain small but essential details you might miss or forget to mention. These details help get to the solution quicker. Also, they are more effective than text alone because it removes the need for others to guess what you're experiencing. People can see the issue for themselves.
Code snippets and gist links are also valuable because people can take your code and run & test it locally.
Once again, let's continue with the previous example and modify it to contain supporting material.
Hey! I cloned the project and tried to run it locally on my Macbook. I added all the required environment variables and started the required Docker containers: mailbox and database. The node version is v20, and the npm version is v8. However, when I ran "npm run dev", I got an error saying "npm ERR! missing script: dev".
Steps to reproduce:
- Go to https://github.com/user/repo
- Clone it to your machine
- Create an env file and add the required env vars (next_public, db_host, and secret)
- Run npm install (you'll need node@v18 and npm@v7)
- Run npm run dev
So far, I've tried the following solutions:
- Checked the npm scripts in "package.json" to ensure "dev" is actually defined. It's there, and it still doesn't work.
- Tried running "npm install" again to make sure all dependencies are up to date. No luck. Same error.
- Googled this error message and tried a few suggested fixes, like deleting the "node_modules" folder and reinstalling everything.
I attached a screen recording here, so you can see what happens when I run the command. I also attached a screenshot with the error and pasted my "package.json" file below.
Since the "package.json" file is available, people can go through it and see a typo with the "dev" command. As a result, your help request is quickly solved.
5. Describe your goal
Lastly, describe what you're trying to do - don't simply say "help". Once again, people can't guess what you want to achieve.
Clearly state what you aim to achieve with your application or code.
Continuing with the same example, you could say something like this:
Hey! I cloned the project and tried to run it locally on my Macbook. I added all the required environment variables and started the required Docker containers: mailbox and database. The node version is v20, and the npm version is v8. However, when I ran "npm run dev", I got an error saying "npm ERR! missing script: dev".
Steps to reproduce:
- Go to https://github.com/user/repo
- Clone it to your machine
- Create an env file and add the required env vars (next_public, db_host, and secret)
- Run npm install (you'll need node@v18 and npm@v7)
- Run npm run dev
So far, I've tried the following solutions:
- Checked the npm scripts in "package.json" to ensure "dev" is defined. It's there, and it still doesn't work.
- Tried running "npm install" again to make sure all dependencies are up to date. No luck. Same error.
- Googled this error message and tried a few suggested fixes, like deleting the "node_modules" folder and reinstalling everything.
I attached a screen recording here, so you can see what happens when I run the command. I also attached a screenshot with the error and pasted my "package.json" file below.
I want my app to start locally when I run "npm run dev". Also, I'd like to modify the command to be "npm run local-dev" instead. Can anyone help me, please?
Make it straightforward for people to understand what you're trying to achieve. It'll increase your chances of getting help.
Putting everything together
Now, let's combine everything you learnt and create a template you can reuse.
"Hey! I struggle with this issue [describe issue]. Here are the steps to reproduce the issue [add steps]. So far, I've tried these solutions [show solutions]. Here's a link to my code [introduce link] and a screen recording [add screen recording]. I want my code to do [say what]. Could you help me, please?"
It's important to mention that it's not always required or possible to follow all these steps and create an elaborate question. Don't feel pressured to do it just for the sake of doing it. Just ensure you make it easy enough for other people to help you.
Remember this quote whenever you ask a question - "help other people help you".