Writing good issues

Why does it matter?

A well written issue will reduce the amount of back-and-forth communication required between the client and the developers by clearly stating the goals and expectations in play from the very beginning.

A well written issue will:

• reduceReduce the cost of development by reducing time taken for developers to find the cause of the issueissue.
• reduceReduce the cost of development by preventing issues from being sent back to developers for changes due to misunderstandings around the user goalsgoals.
• helpHelp identify any alternative solutions by maintaining a focus on user goals and not specific software interactionsinteractions.
• keepKeep development focussedfocused on the higher-level goals of the project and allow developerdevelopers to spend time on the work that provides the most valuevalue.

What makes a good issue?

• User Goals: What were you aiming to achieve when the issue occurred? Try to keep it as high-level as possible, so instead of "I want to submit the order form with Jan 21st as the date", try "I want to place an order for Jan 21st"
• Expected Behaviour: What should have happened?
• Actual Behaviour: What happened that was not expected?
• Steps to Reproduce: What was done prior to the unexpected behaviour that developers can use to reproduce the issue for investigation? What information was input ofand what buttons were pressed?
• Background Information: Further information developers may need to reproduce the issues. This may include:
  
  • What account were you using when the issue occuredoccurred?
  • What version of your operating system / browser were you using when the issue occuredoccurred?
  • What was the URL of the page you saw the issue from (copied and pasted into the issue)?
  • Any files that may be relevant to the issue (attached to the issue).
  • Screenshots of what you are seeingseeing.