#2782

Where Bugs Really Go To Die, Your Product Documentation

From somewhere not so agile and written from a documentation writer’s perspective.

We’ve all heard this story…

Too many bugs to fix for the Beta 1 milestone? Punt them to Beta 2. Of course during the Beta 2 milestone you fix some of the high priority bugs from Beta 1 but find more bugs in Beta 2. Still too many bugs? Punt them to the Final Release milestone. Fix some more bugs, find some more bugs. Hopefully your team is fixing them fasted than they are finding them so things slowly improve. But now there’s nowhere to go.

So you start pushing the bugs that can’t be fixed to documentation. It’s so easy. All you have to say is “we’ll just document that”. Say it enough times and “No Bugs!” simple.

This has a couple of unappreciated and unintended consequences…

Firstly this makes the documentation writer’s job much harder. Explaining each of those weird little caveats takes far more effort than you might imagine. Good writers are trying to show your product in the best possible light. That’s hard when they’re trying to cover up all the defects.

Secondly you end up with lengthier hard to read product documentation full of caveats and additional information describing the weird product behavior all those bugs caused.  This doesn’t really change anything. “Fix” or “Don’t Fix”. All postponing to the next milestone or release does is drive unseen work downstream and adds risk to the project as some bugs may be hiding large work items. For the most part get the bug fixed immediately; this iteration or the next. This has the added benefit of not cluttering up your bug tracking system with postponed bugs. I’ve seen bug tracking systems with thousands of bugs that just hung around, they were never going to get fixed. Rank bugs alongside new product features. Rank them during iteration planning. Get the Product Owner to choose between new work and fixing defects.

Use your writer’s skills. Really you want a writer on the team from really early in the project. Writers, like good testers, can give you a lot of feedback on how usable your product is. If your writer is telling you something is going to be hard to explain to users then it’s fair to think it’s going to be hard for users to understand.

Quantify your bug debt. Use historical fix rates or estimate them in iteration planning. The Product Owner may be tempted to try and push lots of small bugs out by prioritizing features ahead of them. One way to get them thinking is to tell them that if they wanted to ship today and didn’t want to ship with any of those bugs then it’ll take another X days to really be done.

Don’t be afraid to cut. Don’t integrate bug ridden features and don’t be afraid to cut features that have unexpected bugs. It’s far easier to tell users that something isn’t supported than it is to guide them through a series of word around steps to get a badly written feature to work.