How To Ask A Good Question ❓

:wave: There’s a good chance you’ve joined the Atlassian Developer Community because you have a question :question:. Well, you’ve come to the right place!

The Atlassian Developer Community is a great place to ask fellow developers for advice on questions you have. However, not all questions are alike. We’ve put together some tips on how to improve the chances that your question gets answered.


tl;dr:

  • Search for existing questions and answers
  • Give as much context as possible and add references to the documentation you’ve already read
  • Provide well-formatted, helpful code to reproduce the issue
  • Be ready to respond to questions, try out potential solutions, and mark great replies as solutions

As a rule of thumb, if your question is less than a few sentences and doesn’t include any links to docs, code snippets, nor images, then it is probably not a good question.


Search for existing topics

The Atlassian Developer Community has been around for a while and has a plethora of great questions and answers. Even if you don’t find the answer to your question, it can be helpful to reference existing discussions to provide additional context.

Category. Category. Category.

We use Categories to organize discussions. Generally, there is a top-level category for a given product or platform and a set of sub-categories within it. For instance, the Jira category has a number of subcategories: Jira Cloud, Jira Cloud Announcements, Jira Server, Jira Data Center, and Jira Server Announcements. Each category and sub-category contains discussions specific to that product or platform. Therefore, developers and Atlassians active who specialize in those products and platforms are most active in those categories.

When creating a new topic, be sure to select the category that is most relevant to your question.

Write a title that summarizes the specific problem

The title is the first thing potential answerers will see, and if your title isn’t interesting, they won’t read the rest. So make it count:

  • Pretend you’re talking to a busy colleague and have to sum up your entire question in one sentence: what details can you include that will help someone identify and solve your problem? Include any error messages, key APIs, or unusual circumstances that make your question different from similar questions already on the site.
  • Spelling, grammar, and punctuation are important! Remember, this is the first part of your question others will see - you want to make a good impression. If you’re not comfortable writing in English, ask a friend to proof-read it for you.
  • If you’re having trouble summarizing the problem, write the title last - sometimes writing the rest of the question first can make it easier to describe the problem.

Examples:

Introduce the problem before you post any code

In the body of your question, start by expanding on the summary you put in the title. Explain how you encountered the problem you’re trying to solve, and any difficulties that have prevented you from solving it yourself. The first paragraph in your question is the second thing most readers will see, so make it as engaging and informative as possible.

Try to avoid asking multiple questions on a single topic. If you have a number of questions, break them into individual, succinct questions.

Include as much context as possible

Even if your question is straightforward, help others help you by providing as much context as possible. Some things you should consider sharing:

  • What documentation have you already looked at?
  • Where did you expect to find the documentation but couldn’t find a reference to the thing you are digging into?

Bad:

Is it possible to create a custom field via an API call?

That is quite the sparse question, eh? It’d be frustrating if someone just responded back with Yes, wouldn’t it? :face_with_raised_eyebrow: Let’s see how we might expand the question to get to a better solution….

Good:

I’m trying to create a custom field in my instance of Jira Cloud. I am making the call from a local development environment that is running a small Node app.

I’m using this route to make a POST request: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields/#api-rest-api-3-field-post

The body of the request looks like:

{ Nice code snippet here }

The problem I’m running into is that I’m receiving a 543 whenever I make the request - regardless of which user’s authorization I have. I’ve looked through the https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#async-operations documentation on status codes and did not find anything on the status code I’m receiving. Additionally, I’ve looked through old posts on CDAC regarding status codes but nothing seems to cover this status code .

Any recommendations on what I should be doing differently?

Oh wow! Much more information. :star_struck: We know this person has already looked at docs, searched through existing issues, and isn’t looking for a Yes or No answer.

As a rule of thumb, if your question is less than a few sentences and doesn’t include any links to docs, code snippets, nor images, then it is probably not enough.

Help others reproduce the problem

Do some work to debug the issue down to the minimal set of code that is causing problems. Then, share a code snippet of where you believe problems may be occurring. Don’t share an entire files’ worth of code! Only share relevant, contextual pieces that will aid others in reproducing and debugging the issue. Some tips on when and how to share code:

  • Include the smallest amount of code that allows others to reproduce the problem. For help with this, read How to create a Minimal, Complete, and Verifiable example.
  • If it is possible to create a live example of the problem that you can link to (for example, on https://glitch.com) then do so - but also copy the code into the question itself. Not everyone can access external sites, and the links may break over time.
  • DO NOT post images of code, data, error messages, etc. - An image may be worth a thousand words, but when it comes to code, none of those words help get your question answered! Anything that is text-based should be copied and typed as text into the question. Only use images for showing how something is being misrendered in a UI component.
  • Format code snippets. The easier and cleaner your question is to read, the better. The topic editor uses markdown for formatting so you should take the time to format your code accordingly. No one wants to read through code that has an obscene number of tabs and requires an immense amount of horizontal scrolling.

Proof-read before posting!

Take a second to re-read :face_with_monocle: what you’ve written. Does it make sense? Is it clear? Would you want to answer this question out of the goodness of your heart? Ensure that any code you’ve included is formatted and can be used to reproduce the question. Make sure you haven’t included any sensitive information you don’t want to share with the entire world.

If you have doubts, ask a colleague or friend to give it a look. What questions do they have for you after reading it? Answer those questions in your question before making the post.

Be ready to answer questions about your issue

Oftentimes, getting to an answer requires someone asking some clarifying questions about what you’re seeing on your end. Make sure to provide prompt and thorough responses to ensure that others have as much context as possible. Be ready to try out the solutions offered and provide feedback on what happens when you give them a try.

Mark solutions as solved

When your question gets answered, take the time to mark the answer as a solution. This makes it clear to future developers that your question was solved and which response was the solution.

To mark a response as the solution, click on the ellipses at the bottom right of the reply:

1

This will open a menu that includes an option to mark the response a solution:

A reply marked as a solution will look like this at the bottom:

Even if you answered your own question, you can still mark it as a solution!

Don’t crosspost known, existing issues

If you already have an open ticket somewhere else (DEVHELP, JRACLOUD, etc.), don’t crosspost it to CDAC to try to get more eyes looking at it. It can be tempting to crosspost something you’ve already submitted, but it won’t affect its priority in the queue.

It is OK to crosspost if you’re asking other developers whether they have a solution for working around the issue.

Don’t post secrets or personal information

Ensure your sample code does not include any security information (i.e., instance name, email, and API token with an API request). Posts that include any compromised information may be removed down and a security incident filed, if necessary.

Don’t at-mention random community members

It can be frustrating when your question doesn’t get answered right away. But that doesn’t mean you should start @mentioning CDAC users who you know are active. We’re all here doing our best to make sure we’re helping each other out. Be the change you seek and help answer others’ questions. A bit of good karma goes a long way!

Not all Atlassians are experts across all of Atlassian

Although we try our best, not every Atlassian can be an expert on every product, platform, and API. Don’t assume all Atlassians know about all features and functionality of the Atlassian products you’re using.

Additionally, not every Atlassian knows where to find an issue or piece of documentation without a direct link to the issue or documentation. Please directly link to any mention of tickets or documentation in your post or comments to make it easier for us to retrieve the information you’re referring to.

Look for help asking for help

In spite of all your efforts, you may find your questions poorly-received. Don’t despair! Learning to ask a good question is a worthy pursuit and not one you’ll master overnight. Here are some additional resources that you may find useful:

15 Likes

Pretty nice of you to write this down. Thank you for putting in the effort.

Wouldn’t it be good idea to pin this post maybe?
For example, right under “Welcome to the community!” pinned post.

3 Likes