How to write a product issue someone can fix
A small structure for turning an observation into useful evidence.
Name the user’s interrupted task
Begin with what someone was trying to accomplish. “I was replacing the homepage image” gives the issue a purpose. Then describe the interruption without diagnosing it prematurely. “The old image returned after reopening the page” is an observation. “The database is broken” is a conclusion that may not follow from what was visible. Keeping those separate helps the person investigating start in the right place.
Describe the starting conditions
Record the relevant page, device and account state in plain language. A problem experienced while signed out may differ from one experienced after signing in. A freshly created page may differ from a saved one. Include only details that help recreate the situation. Do not paste passwords, session information, customer records or a full private screen into an issue report.
Write the shortest repeatable sequence
Use numbered actions that another person can follow from the stated starting point. For example: open the sample page, replace the header image, save, close the editor and reopen it. If the issue does not happen every time, say that. Record a successful attempt as well as a failed one when it reveals a meaningful difference. A reliable sequence is more useful than a confident guess.
Separate expected and observed behaviour
State what should have happened and what you actually saw. “Expected: the replacement image remains after reopening. Observed: the previous image appears.” This simple separation prevents a long paragraph from hiding the central problem. Add one focused screenshot or short recording if it clarifies the observation; more attachments are not automatically better evidence.
Explain the practical consequence
Tell the reader whether the issue blocks publication, causes lost edits or adds an extra step. Avoid assigning urgency solely because a screen looks unusual. A spelling error in a decorative caption and an enquiry that never arrives have different consequences. Describing the impact lets the team decide where the issue belongs alongside other work.
Close with the same task
When a fix is ready, repeat the original sequence on the updated product. Check that the result persists through the point that previously failed. Record the outcome and any remaining condition you could not verify. This is a general approach to product review, illustrated with a fictional image-replacement issue; it is not a report of a real defect or a claim about completed testing.