The Developer Needs More Than “the Button on the Right”
Write a website issue report a developer can reproduce. Use the template to capture the page, element, conditions, steps and expected versus actual result.

“The button on the right doesn’t work” leaves a developer several questions away from the problem. Which page, which button, which screen size, and what happened when you used it? A useful report lets someone attempt the same action under recognisable conditions.
Describe the visible failure before diagnosing it
Name what you tried and what you observed. “After I submitted the enquiry form, the page stayed on the form and showed no confirmation” is more useful than “the form script is broken.” The first describes evidence; the second assumes a cause that may not yet be established.
The sample below is fictional and uses a reserved example address. It illustrates a report’s structure, not an observed bug or a test we performed. Replace each value with details from the actual environment and avoid including real customer data in screenshots or sample submissions.
Use this implementation-ready report template
Summary: Enquiry form shows no confirmation after submission on narrow screen
Location: https://example.com/project-enquiry/ — project enquiry form, “Send enquiry” button after the message field
Environment: Staging; review version dated 19 November. Record the actual browser name and version, operating system and viewport dimensions used.
Starting condition: Visitor is signed out. Form is initially empty. Use the agreed harmless test details.
Steps: 1. Open the page directly. 2. Complete the required fields with the test details. 3. Activate “Send enquiry” once. 4. Wait for the expected response and record what appears.
Expected: The agreed confirmation state tells the visitor whether the enquiry was accepted and what happens next.
Observed: Describe the actual visible message, page change or absence of feedback. Record whether entered text remains. Do not infer whether an email was delivered from the page alone.
Repeatability: State how many attempts you made and the outcomes; if not retested, say so.
Evidence: A screenshot showing the form and any visible message, plus the time of the attempt. Redact personal information and access tokens.
Use a stable description of the element
“On the right” can change meaning when the layout rearranges on a phone. Pair the page address with a visible label and surrounding context. If two buttons have the same label, explain which section contains the relevant one. A screenshot annotation can help locate it, but it should not replace the text someone needs to repeat the action.
Record the conditions that could matter without turning the report into a system inventory. A signed-in preview and a signed-out public view may be different starting points. Likewise, a specific viewport helps another person attempt the same layout. If you do not know a detail, mark it unknown rather than guessing.
Keep expected behaviour separate from observation
The expected result should come from an agreed requirement or a clearly stated question. “It should work” does not define the finish. If the confirmation wording has never been decided, say that the requirement is unresolved. The developer may need a product decision as well as a technical investigation.
Mozilla’s bug-writing guidance emphasises precise reproduction steps and separate expected and actual results. Those principles are useful here even though a client-website report has a different audience and workflow. You do not need to copy an entire browser-project reporting process to make one website issue understandable.
Report one issue, then verify the same question
Keep an unrelated spelling correction out of the form-failure report. Link separate issues if they appear connected, without asserting a shared cause. When the developer provides a revision, return to the original route, conditions and steps. Record what now happens and whether another state remains untested.
A completed report is not proof that the failure affects every visitor. It is an inspectable starting point for implementation and a way to recognise whether the stated problem has been addressed.
Include the location, the conditions and the observed behaviour before proposing a fix. A visual feedback method is worth evaluating on whether it preserves those details for implementation.
A useful next step
For the next decision, read A Client Comment Is a Clue, Not Yet a Design Instruction and “Resolved” Is Not the Same as “Ready to Launch”.




Discussion 0
What did this article make you think about?