Issue Tracking

There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult.

Sir Charles Anthony Richard Hoare

There are a great many issue tracking systems in existence, from the now venerable bugzilla, to newer systems like Trac, or Jira. We've built our own from scratch. Why? We built ours because we wanted something very simple, that we could integrate tightly with our other project management tools. We also felt like most of the existing solution had too much functionality, that people often just ignored. There are two main reasons to use an issue tracker. One is to communicate between someone who has noticed a problem with a piece of software and the person responsible for fixing it. The other is to maintain a historical record of what issues have been fixed, and most importantly, how they've been fixed. To a certain extent, these two issues are at cross purposes. When you want to communicate with someone, you want to do it as simply and directly as possible. When you want to analyze the history of a projects issues, you want to have a richly annotated data model to search through.

Features supporting the archival use of an issue tracker often dominate the user interface. They get in the way of simple, direct communication. Not to put to fine a point on it, but filing a bug in bugzilla can at times feel like filling out IRS paperwork. That isn't how we want our clients to feel when they are trying to tell us how we can do something better.

We've attempted to take a middle road between supporting the archival use of our issue tracker, and the communication use of it. We've decided to use a technique called Semi-structured data. The relational model we use is very simple, we keep track of issues, who they are assigned to, and what their status is. We allow users to write a description of an issue, and to comment on the issue. The semi-structured aspect comes in the form of something called Restructured Text. Restructured Text is a very simple markup language, along the lines of what one uses to create Wikipedia pages. If a projects' issues are of sufficient complexity that long term issue tracking proves necessary, we can simply use Restructured Text to annotate the description or the comments with easily machine-parsable metadata that we can later extract when we need to data mine.