Writing Annotations

…add stuff

Where should we add notes?

If your dev team is heads-down, concentrating on tasks at hand, or it is the middle of the night when you get to looking at things, it is pretty annoying to interrupt them. I’ve found it best to give feedback on user stories asynchronously.

We could use email for feedback, but I find this gets a little messy. Emails can get buried in inboxes, so it is difficult to find them when the time comes. If you do choose to email feedback, make sure to use a consistent title in the Subject line of the email so the devs can easily filter for the information when the time comes.

Our team tracks user stories in JIRA, so I give my feedback by uploading screen shots and writing notes in a “Comment” on the ticket. This way, whoever on the team picks up the ticket next can see my notes.

<show JIRA ticket with Comments section>

Talk to your dev team about the best place to add your feedback on the user stories.  Most teams use a tool like JIRA for their workflow, and they’ll probably be pleasantly surprised if you ask to be added to the system to smooth the flow of communication!

What to Write

Every comment should include:

  • User Story Number / Title
  • Date / Feedback Number
  • Screen shot / Video
  • Numbered Annotations
  • Hardware / Software you’re using.


User Story

Your User Stories should be numbered to make them easier to track and talk about. On our team, our stories are named, for instance O2O-144: Export PDF of Invoice <Image that breaks down this number>, but yours may be named differently.

If the team is using a system like JIRA, this step is unnecessary, feedback can be added straight to the user story itself. If you’re sending feedback over email, however, it is important for the devs to know what you’re talking about!

Feedback Number / Date

On a few stories, there may be a lot of back and forth before the story passes. I’ve found it useful to give a feedback number each time I give notes on a user story so I can reference things that have been fixed or worked on in the past.

Screen Shot / Video

Attach the screen shot or video you took in the previous step.

Numbered Annotations

This is where those annotated screen shots come in! Next to each number, write a note about the problem. Generally speaking, more information is better, but make sure to include:

  • What happened
  • What you expected to happen instead
  • Any additional information that will help clarify  things to the devs

<Image of the screen shot and annotations>

Hardware / Software

The devs will want to replicate the issue so they can figure out how to solve it. For this, it is important for them to know what you tested on. Include:

  • Version Number of the Build (if your teams is working with multiple builds)
  • Browser you’re using if you’re testing on the web.
    • Chrome, Safari, Internet Explorer, Edge, Opera, etc…
    • Version of the browser
  • Operating system you’re using
    • Windows, Mac OSX, Linux, Android, iPhone (iOS)
    • Version number of the operating system
  • Hardware you’re using
    • Windows machine, Mac, iPhone, Android, Windows Phone, etc…

Sometimes these things – particularly version numbers – are hard to remember, so I keep them written down. This way, I can just copy and paste them into the ticket.

<Screen shot of hardware/software description>

Wrapping Up

Our goal with this – and all – communication is to:

  1. Communicate clearly (so less mistakes occur)
  2. Communicate asynchronously (so we don’t break the concentration of our teammates in the moment, reduce the number of meetings, and be an effective team across timezones)

Give this process a shot for a week or two and adjust it to fit your team’s make up and preferences.
What did I miss? Share your best practices for giving in-progress feedback in the comments below or tweet me @kyle__becker

Categories: How To