How to document a technical problem

A well-documented problem can often be reproduced and fixed. A vague report such as “it stopped working” forces everyone to guess.

Give the problem a precise title

Name the action and failure: “Checkout returns a blank page after UPI selection” is more useful than “payment bug.”

Record the environment

Device and operating system
Browser or application version
Account type or plan
Network type if relevant
Approximate time and timezone
Whether the problem affects one user or many

Write the smallest repeatable sequence

Start from a known state and number each action. Remove steps that do not affect the result. If the problem is intermittent, record how often it occurs.

Separate expected and actual behaviour

Describe what should happen, then what happened instead. Include the exact visible message, status code, or incorrect result without interpreting it prematurely.

Attach safe evidence

Use a short screen recording, cropped screenshot, console message, or sanitized log. Record the time so server-side logs can be matched. Remove secrets and unrelated user data.

Track experiments

For every attempted fix, record what changed and the outcome. Changing several things simultaneously makes it difficult to know which action mattered.