Wednesday, November 4, 2009

State Your Purpose

Being a tester, I see a lot of tickets. Some tickets, unfortunately, hang around for a while, and tend to be worked on by multiple people. These wind up with the basic ticket writeup and a series of comments by different people. Particularly when the ticket is a difficult one, there are theories being tried and discarded.

Let's use an example:
We have an issue where access to the system, either for standard use (reading, writing data over mounts) or for diagnosis (logging in to the box) was slow. The system had several exported mounts, was performing replication, and was deployed in our lab. That's about all we knew going in to it.

As we're working on the ticket, a lot of theories came up, ranging from load on the box to a kernel problem to a network issue (turned out to be saturation of the switch when other system using that same switch we engaging in network-intensive operations).

So the question becomes, how do we talk about this in the ticket? There are good and bad ways to write this up.

A Poorly Written Comment
The replication schedule is:
- 20:00 (average duration: 90 min)
- 07:00 (average duration: 45 min)
- 13:15 (average duration: 80 min)

A Well Written Comment
We noticed that the slowness described only occurs sometimes. Looking at what the box is doing at the time, it always seems to be replicating.

The replication schedule is:
- 20:00 (average duration: 90 min)
- 07:00 (average duration: 45 min)
- 13:15 (average duration: 80 min)

We've seen slowness at:
9/12 21:10
9/13 07:08
9/16 07:14

Earlier comments in this ticket indicate that load average is not the problem, but what else might replication be triggering? Early thoughts: increased threads, increased memory use, increased network use...

The Six Month Test
A good comment is one that makes sense six months later, after you've forgotten all the details. This means it needs to:
  • describe how it relates to the issue as a whole
  • describe what the reader is intended to do or take away from the comment
Just like your bugs, write your comments for posterity. Future you will thank you.

1 comment:

  1. "A good comment is one that makes sense six months later, after you've forgotten all the details."

    Excellent!

    ReplyDelete