Keeping your bug tracker simple

I doubt Albert Einstein was thinking of bug trackers when he (supposedly) said “everything should be made as simple as possible, but not simpler”, but it certainly applies. An overly-complex bug tracker discourages filing bug reports. An overly-simple bug tracker makes it hard to scale the reporting, filtering, and resolution of bug reports. When you get the bug tracker’s complexity just right, you make life better for your community.

Why is this important?

A wise me once said “bug trackers are the cornerstone of building an open source community.” Standing up a bug tracker won’t make a community magically appear, but not having one makes it nearly impossible to develop software that you want other people to use. Your project’s bug tracker is the first — and sometimes only — interaction you have with users. A bad experience puts them off of not only providing a valuable bug report, but maybe even off using your software further. And they almost certainly won’t stick around to get more involved in the community. Your bug tracker is the opportunity to make a good first impression.

Too simple

The barest bug tracker supports a free-form description and an open/closed state. While this simplicity sounds appealing, you may find it’s less awesome in practice. A few other features make it useful:

• A title/summary field — what is this bug about at a glance?
• State — is this being worked on? Is a fix pending?
• Names — who reported it? Who is assigned to it?
• Comments — what’s new? What questions does the person working on it have?
• Type — is it a bug or a suggestion?

This is only a small list, but it represents what I would consider a bare minimum. Most every bug tracker I’ve used supports most of them out of the box. State and type are the exceptions, but they can usually be easily implemented.

Of course, you can probably think of several other things to include: affected version, operating system, hardware, and so on. Chapter 10 of Program Management for Open Source Projects has two full pages of attributes that you might want to track.

All of these things help you better understand a bug at a glance, but also to report on bugs in aggregate. This allows your community to more quickly triage and fix bugs, and to look for patterns that can enable you to catch bugs sooner.

Too complicated

Filing a bug report is work. Worse, it’s work that you ask people to do for free when they’re already frustrated. All of the advanced features and settings that make life easier for you complicate the process for them. Every field you add to the bug tracker is something else the potential reporter has to think about. The frustration compounds if the meaning of the field isn’t obvious or if it’s irrelevant to them. At some point, their frustration exceeds the hoped value of getting the bug fixed and they go away.

All of that metadata you’re tracking to make your life easier just made your users’ life harder. And a bug tracker isn’t particularly useful if it scares away all of your bug reports.

Finding the balance

One solution is to limit the advanced fields to members of a particular group. If the people triaging and fixing the bugs can see the “internal” fields but the outside users can’t, you get the best of both worlds. You can also hide the complicated fields under an “advanced options” menu and let people make the choice about the amount of complexity they see. You can even have a form that collects just the basic information and creates the bug on behalf of the user.

None of the solutions in the previous paragraph are universally available, and they all likely require at least some amount of development work. This distracts you from the work of the project. A better approach is to add complexity only when necessary.

I understand the temptation to think ahead. You have all of these ideas of how you’ll have your bug tracker magnificently organized. You spend a bunch of time planning it out, configuring it, and then nobody uses it they way you want because they don’t understand it.

Instead, start with the basics. Solve problems after they become problems. As your community grows or your software becomes more complex, the bug tracker will need to evolve to support the changing needs. This will typically mean adding more fields (and thus more complexity) because you’re asking the bug tracker to bear more of the information sharing and retention load. That’s okay, though, because you’re keeping it as simple as it can be (and not simpler).

This post’s featured photo by Andre Mouton on Unsplash.