# Quality issue reporting

### 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 focused 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?

- **Keep It Small:** An issue should be as small as possible and address only a *single* bug or feature. As a rule of thumb, if an issue can be "partially completed" it likely needs to be broken into smaller issues
- **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