To give feedback developers can act on, report one issue per message and include four things: what you were doing, where it happened (the page address and your device), what you expected, and what actually happened. Attach a screenshot. A developer who can reproduce a problem can usually fix it quickly.
We show clients working software early, in the first week or two, specifically so they can tell us where we got it wrong. That only works if the telling is usable. The quality of feedback decides how fast a project moves more than almost anything else a client controls.
We are on both sides of this. We build for clients, and we run our own products, so we are also the users who find the problems. A report that gets fixed quickly and a report that takes a week differ in predictable ways.
The difference is not technical knowledge. It is four pieces of information.
What makes feedback easy for a developer to act on?
Feedback is easy to act on when a developer can reproduce the problem without asking a question. That requires four facts: what you were doing, where it happened, what you expected to see, and what you saw. Missing any one of them usually costs a round of messages before work can start.
Most of the time spent on a bug goes to finding it, not fixing it. A developer who can make the problem appear on their own screen is most of the way to a fix. A developer who cannot is guessing.
"Where" matters more than people expect. Vortech AC and Electrical has a 108-page site, with a page for each service in each city. "The phone number is wrong" could refer to any of them. The page address turns a search into a fix.
What should a bug report include?
A bug report should include the action you took, the exact page address, your device and browser, the result you expected, and the result you got, plus a screenshot. Add the time it happened if the problem involves a form, an email, or a payment, so it can be matched to the logs.
Here is the template. Copy it.
- What I was doing. The steps, in order, from a starting point anyone could find.
- Where. The full page address, and whether you were on a phone or a computer and in which browser.
- What I expected. One sentence.
- What happened instead. One sentence, with the exact wording of any error message.
- Screenshot or recording. Attached, not described.
A filled-in example:
What: Filled in the quote form and pressed Send.
Where: /contact/ on an iPhone, Safari.
Expected: A confirmation message.
Actual: The button greyed out and nothing else happened.
Tried twice, around 2:15 pm today.
Screenshot attached.That report can be worked on immediately. Compare it with "the form is broken", which leads to three questions and a day's delay.
Why send one issue per message?
Sending one issue per message lets each problem be tracked, assigned, and closed on its own. A single message containing six issues is finished only when all six are, so it stays open for days, and the small fixes inside it wait on the hard ones.
One issue per message also makes the reply clear. "Fixed" attached to a single report means something. "Fixed" attached to a list means you now have to check which items it covers.
If you have many small items from one review session, a numbered list in one message is a fair compromise. Numbers let both sides refer to "item 4" without quoting it.
Why do screenshots help so much?
Screenshots help because they capture details you did not think to mention: the page address, the browser, the screen width, the state of the form, the exact wording of an error. A developer often spots the cause in the image before finishing the text.
For anything that involves movement or a sequence, such as a menu that closes too early, a short screen recording is better still. Phones and computers can both record the screen without extra software.
On document tools, attach the output. CaseCobra, our practice management product, generates 37 types of Arizona criminal documents. "The motion came out wrong" could mean any of the 37. The generated file, with a note saying which line is wrong and what it should say, is a complete report.
How should you ask for a change that is not a bug?
Ask for a change by describing the problem you want solved, not the solution you have in mind. Say who is affected and what they are trying to do. The developer may know a simpler way to get the same result, and the problem statement lets them offer it.
| Less useful | More useful |
|---|---|
| "Add a dropdown for city." | "Customers keep typing the city wrong, and we cannot sort leads by area." |
| "Make the logo bigger." | "On my phone the logo is hard to read next to the menu." |
| "This page needs to pop." | "The page does not say what we charge, and callers always ask." |
| "It is slow." | "The services page takes several seconds to show anything on my phone on mobile data." |
A change request is also the moment to check the plan. If the change is outside the agreed scope, say so openly and decide together whether it replaces something or is added. Our post on how to prevent scope creep covers how to keep that from becoming a dispute.
How do you prioritize a list of feedback?
Prioritize feedback by sorting it into three groups: things that block launch, things that should be fixed soon, and things that would be nice. Tell your developer which group each item is in. Without that, every item looks equally urgent and the order of work is a guess.
A broken payment form and a slightly wide margin are not the same class of problem, and only you know which details your customers will care about. One person on your side should collect and send feedback. Two people sending opposite instructions is a common and avoidable delay.
For how review rounds fit into a whole project, see the software development process, step by step.
Frequently asked questions
Is it better to report bugs by email, chat, or a call?
Written is better than spoken, because a written report can be searched, forwarded, and checked off. Use whichever written channel your developer asks for, and keep to it. A call is useful for discussing direction, not for reporting defects.
What if I cannot make the problem happen again?
Report it anyway, and say that it happened once. Include the time, the page, and what you were doing. Intermittent problems are real, and the time lets a developer look for the matching entry in the error logs.
How do I find out which browser I am using?
On a computer, open the browser's menu and look for "About". On a phone, the name of the app you tapped to open the page is enough. If you are unsure, a screenshot of the whole screen usually answers it.
Should I tell the developer how to fix it?
Say what is wrong and what you want instead. Suggestions are welcome, but lead with the problem. A fix aimed at the wrong cause can hide the real one.
What if I simply do not like how something looks?
That is valid feedback. Say what it is failing to do, or point to an example you prefer.
If you want a team that asks for this kind of feedback early and acts on it, tell us about your project.