When you have a problem with a software project or library, often the best way to ask for help is through text. Different projects offer support in different ways, such as email, chat rooms, or GitHub issues. Most of the time, the people helping you out are unpaid volunteers, so it's polite to respect their time by structuring your question well up front.

Here's an example of a bad question:

<newbiecoder123> why doesnt this work??

It's really hard to understand what's going on here! The user hasn't told us what they're trying to do or what the issue is, the screenshot is hard to read, and we don't have enough information to help them. It's going to be very hard to help this person figure out what's wrong.

Here's how to ask a good question:

Structure

What are you trying to do?

Start by summarizing your problem briefly. Keep this to one sentence. For example:

• "I'm trying to make a POST request to a web server."
• "I'm trying to run the application locally."
• "I'm running into a bug and I'm not sure if it's my fault."

Often, we forget to give people the full context of what we're trying to do. Saying this up front helps a volunteer understand what you want to do.

What have you attempted?

If you're inexperienced with a tool, it's quite possible you're using it wrong. Complex tools often have multiple ways to use them, or subtle ways in which they can be misconfigured. State what you've tried so that the helpers know what they can skip past. For example:

• "I used this example from the documentation:" (with a link to the docs and example in question)
• "I ran this command in my terminal:" (with the command you used)
• "Here is the code I am running:" (with a code snippet)

When you're asking for help with a programming language or library, make sure to include the code that is causing the problem. The secret benefit of including readable code is that it nerd snipes people into mentally engaging with your problem, so they'll probably help you out sooner rather than later.

If you include a code snippet, try to cut it down to the smallest block of code which demonstrates your issue. If you post multiple pages of code, people tend to ignore you; if you only post ten lines, it's much easier for someone to see what you're trying to do.

What happened?

Tell the volunteers what actually happened when you tried to use this tool. This could be something like:

• an error message from your terminal
• a stack trace from a program crash
• a screenshot of the issue (only if you can't copy and paste the text)

Try to give people the full error message, but omit extraneous information that you don't think is related to the crash.

When possible, prefer copying and pasting text into a code block rather than attaching a screenshot. Screenshots are not accessible – they do not render properly on some mobile devices, and they cannot be easily read by screen readers.

What did you want to happen?

Now tell the volunteers your expected behavior. This is what you want to happen, and what you believe should reasonably be happening given the code you posted. This could be that:

• you didn't expect an error to occur
• you expected an action to complete
• you expected a program to start sucecssfully

Often, this is obvious, but sometimes you might be forgetting to include context because you take the goal for granted. If a volunteer doesn't know what you're trying to do, it's hard for them to help you get there. So make sure to include this part.

Complete example

Here's what a well-asked question looks like:

Hello! I'm trying to start a Node web server using this code:
...snippet of TypeScript code...

I have tried to start it by running node index.js in my terminal.

However, when I run node index.js command to start the server, I get this error message:
...snippet of a stack trace...

What I expect to happen is that my webserver starts on port 8000 and answers requests.

Does anyone have experience with this error who could help me?

Etiquette

• Don't demand help. You're using free, open-source software – you get the support level that you pay for. Most of the time, authors and experts want to help you have a good experience with their software. They're volunteering to help you – they don't owe you anything.
• Don't be bothersome. Pings can be disruptive to peoples' focus or work days. Often, volunteers are helping people out in their spare time between other important things in their life. If someone doesn't get back to you for a while, they may be away from their computer, or busy, or they may have gone to sleep. In general, asynchronous, slow notifications such as email or a GitHub @-tag are OK; instant pings such as a Slack or Discord @-tag are extremely rude.
• Be polite and appreciative. These are unpaid volunteers, and you're getting free help from them! To pay them back for the time and effort they're spending with you, speak politely and express gratitude. Hello, please, and thank you go a long way, and they help ensure other volunteers will want to help you in the future too.

Tips

• Don't ask to ask. Just ask. A help channel is full of folks who are ready to help. Simply go ahead and ask your question, and if you're not in the right place, folks will redirect you to the right place.