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:

• reduce the cost of development by reducing time taken for developers to find the cause of the issue
• reduce the cost of development by preventing issues from being sent back to developers for changes due to misunderstandings around the user goals
• help identify any alternative solutions by maintaining a focus on user goals and not specific software interactions
• keep development focussed on the higher-level goals of the project and allow developer to spend time on the work that provides the most value

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 of 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 occured
  • What version of your operating system / browser were you using when the issue occured
  • 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 seeing