How to write a bug report

What did you do

This is sometimes called "Steps to reproduce".

The purpose of this part is so the person trying to fix the bug can reproduce it. If they can't reproduce it, they probably can't fix it.

The most common problem here is not enough detail.

To help avoid that, it's a good idea to write this as though the person reading it knows nothing about the application or site that you ran into the problem on.

Use words like "typed" and "clicked", not "I did such-and-such task".

Say what you did, not what you meant. Use words like "typed" and "clicked", not "chose" or "selected" or "tried to".

Good starting points: operating system name and version, browser name and version, what URLs you visited (exactly), what you typed and clicked. Pretend you're walking someone through what you did.

Example:

I'm running Ubuntu 16.04.1 with Gnome desktop, using Chrome 54.0.2840.90 (64-bit).
I recreated this in a incognito window (no extensions).
I typed "https://www.example.com" into the address bar,
Then I clicked the "Help" link in the top right.

What did you see

This is the obvious bit to include.

Again, more detail is better. In particular, the exact wording of any messages - copy and paste if you can. A message that sounds generic to you might mean something very important to a developer trying to figure out the bug, if only they know the exact message you saw.

Focus here on exactly what you saw, and not on interpreting it. If it's relevant, provide screenshots, labeling them to match the steps for reproducing the problem. If the problem is an observed behavior, still try to describe it in terms of what you saw in each step, and not how you interpret what you saw. Or provide a video of the bug happening.

And if it doesn’t happen every time, be sure to say so, with a rough idea of how frequently you see it when you do the same things.

Examples:

After clicking "Help", a page loaded with URL
"https://www.example.com/about" and the title "About WidgetCo".

When I click the “Close” button, about one time in ten, the window doesn’t close.

What did you expect to see

This is often overlooked. It's surprising how often I get a report "the site did X" and my reaction is "well, the site is supposed to do X, what's the problem?" Then we have to go back and forth trying to figure out why the person submitted the bug report.

It's much better to include this explicitly, even if it seems obvious to you.

Example:

I expected to see a page with a title like "Help" or
"Using this web site".

Why did you expect to see that?

This is the other often overlooked part.

This can help save a lot of wasted time when it turns out that there's a typo in the documentation, or the user is missing some other part of the requirements, etc.

A documentation error or unclear requirements are just as much bugs as broken code, but it's nice to zero in on what the problem is sooner than later.

Did you expect to see "Y" because requirement 1.2.3 said it should happen? Was it on page N of version 2.1 of the user manual? Did the site help at URL xxxxx say something that led you to expect "Y"? Or maybe your officemate told you it worked that way.

Another benefit is that in trying to find an authority on what was supposed to happen, you might discover that you misunderstood something and what you're seeing isn't a bug at all. Or you realize that what you thought was an authority really isn't.

Example:

In my experience with other sites, links named "Help" go to
pages with help information for using the site, not pages
with information about the company.

Other comments (optional)

You can offer other information that you think would be helpful, but please do it separately from the previous elements - keep the facts separate from the opinions - and keep it concise.

Example:

This looks to me like it's probably just the wrong link.

Let me know if I can help test a fix or anything.

My wife’s cousin’s girlfriend says it might be the frangistan coupling.

Exceptions to the rules

None of this is carved in stone. For example, if starting the application caused my laptop to hang so hard that I had to power it down, I can probably omit describing what I expected to see and why.

More detail is generally better, but keep in mind that developers are human too, and probably won’t read the whole bug report carefully if it looks overly long.