Tips for writing great incident reports

Rayos Training

When reporting a problem on the site, the more information you provide, the faster we can solve the problem. Here is a quick overview of the key tips:

  • Include links to the page(s) where you see the problem
  • If possible, send screenshots/screencasts
  • Indicate what device you are using
  • Tell us what you expected to happen versus what actually happened

Help Our Developers Find The Problem Quickly

By providing as much detail as possible, you help our developers isolate and resolve the problem faster.

For instance, if the “Contact” link on your site is broken, describe exactly where it is on the page, even if it seems obvious. For example,“The problem is the ‘contact us’ link in the footer at the bottom of the page in the first menu at the end.”

The more detailed information you provide, the better!

  • Where is the issue happening? Include links to all impacted pages.
  • We love screenshots/screencasts! Seeing the problem in action is great when we’re troubleshooting.
  • Tell us what type of computer or device you are using (MAC/PC/iPhone/iPad, Android, etc).
  • Tell us what browser (Chrome, Safari, Firefox, IE) you were using when the issue occurred.
  • If you see the problem on multiple devices/browsers, tell us.
  • Did you get an error message? Provide the full text of the error, or a screenshot.

Just the Facts

It’s often tempting to suggest or speculate what you think might be the problem. However, it’s generally better to focus on objectively reporting facts and leave the speculating and troubleshooting to the developer and support team.

Make Sure What You Want Is Clear

What did you expect to happen? Some issues may be subjective usability issues. This is where you want the system to do something because it makes sense for you, but the feature itself isn’t really broken. By clarifying what you expected, it’s easier for us to understand the anticipated behavior and determine whether it’s truly a bug or a usability issue. This clarity also informs our product team of potential usability issues with product.

Include Steps To Reproduce

In many cases a bug is produced by taking multiple steps. In these cases, we may need more than just a link to the page, we’ll need step-by-step instructions so we to can reproduce the issue. Instructions like the following:

  1. Open this page >>
  2. Search for apples >>
  3. Go to the bottom of the page and click the link in the pagination for #2 >>
  4. Once that link is clicked on the format of the list of results looks broken (see screenshot)

Use A Shared Language

In some cases, important information can be lost in translation by not using common terminology. For example, some people call all ad positions “banners,” which can create confusion when you are trying to direct the developer to a specific ad. For more information on web/Rayos common terminology visit our knowledgebase glossary.