looking for a User Guide to write a JIRA Issue [closed]

Question

I'm looking for a User Guide how to write a JIRA Issue.

I'm aware of http://confluence.atlassian.com/display/JIRA/Creating+an+Issue The problem I have is that this documentation is targeted at people having no problem creating Issues and does not explain how to write good Issues and how to decide for example which Priority to use?

I'm looking for something like a common sense approach what belongs in an Issue (or any kind of Ticket) in general.

_{I don't need a "definitive" Guide, just something to get the ball rolling and there are common circumstances that apply to (mostly) all development environments "provide context" "provide all necessary Information / don't refer to Information that might not be available / accessible later" that kind of stuff.}

Answer 1

Depends on the Issue. We do mostly User Stories but if you are going to write an Issue it should contain as much information on the Issue so that anyone working on the card (Developer / QA) has clear goals to what they are trying to achieve.

• Why something needs to be done (Business reason)
• What needs to be done to achieve the goal (Actual task)

A User Story contains this information in its DSL:

As a [Role] In order to achieve [some business value] I want to [have an action]

Example (Taken from the cucumber website):

As a math idiot In order to avoid silly mistakes I want to be told the sum of two numbers.

These stores can be broken down even further into scenarios.

Given I have entered 50 into the calculator And I have entered 70 into the calculator When I press add Then the result should be 120 on the screen

Also the Issue doesn't have to be perfect from the get go. It may come in with some vague requirement which gets built on during a discussion with the client / stake holder. Further clarity gets added during the planning session with the team and finally further detail gets fleshed out when a developer picks up the card and finds that there are some questions still left unanswered.

Cucumber BDD

Answer 2

I find the following guide very useful: How to Report Bugs Effectively by Simon Tatham.

It describes how to optimize your issue text for the programmer. In the end, it gives a summary:

• Be specific.
• Be verbose.
• Be careful of pronouns. Don't use words like "it"
• Read what you wrote.

But this summary is preceded by a good text about writing issue texts.