How to write a bug report that is actually useful.

A useful bug report does not need to sound technical. It just needs to communicate the issue you are having.

When you have built a feature with a tutorial, a code assistant or a few late-night searches, the project may work in the exact state you tested. The next person takes a look at it in a completely different environment and most likely gets an entirely different bug. This is not particularly helpful for anyone, especially not you.

Start with the expected result

Write one sentence about what you thought would happen. Then write what happened instead.

We are going to run with a bug on a task management app as an example for this post.

"After I save a new task, I expect it to appear in the list. The form closes, but the new task isn't there." That's easier to investigate than "the task page is broken."

Give repeatable steps

Use short numbered steps but try to include as much specific information as possible, such as whether the account was new.

A solid report might include:

1. Sign in with a test account.
2. Open the task page.
3. Create a task with a title and due date.
4. Press Save.
5. Note that the form closes, but the task list stays unchanged.

Capture the boundary where things change

If you're comfortable with the browser developer tools, look at the network request when you press Save. Did the browser send it? What status came back? If you have access to server logs, check the same timestamp.

You don't need to diagnose the bug. A status code, screenshot or short error message is enough to help someone narrow it down.

Keep the handoff safe

Use a test account and fake data. Remove passwords, API keys, tokens, customer records and production database dumps. You have one issue you're trying to fix; don't give yourself another. The vast majority of bugs do not need anything close to production data or API access to diagnose, and for those that do. Dummy data and throwaway api keys/accounts should do the trick.

The useful handoff

A good report gives someone else a repeatable failure, the result you expected, the result you saw and a safe way to inspect it.

If possible, also provide information on what tech you are running, version of Node, Python, etc.

You don't need to know exactly what you're talking about when trying to get help, just how to direct the person who does so they can help you as effectively as possible.

PS. Got your bug report and now need someone who knows what they are doing? Visit ancorra.dev for instant final quotes and a money-back guarantee on small-scoped software fixes/changes.