My teammates know that I love investigating and fixing bugs. It’s not uncommon that I’ll take a break from whatever task is on my to-do list to spend time thinking about some esoteric bug report. I also find most technical writing to be unbearably boring. But a good bug-fix story has a lot of value and can be very entertaining.
I want to explain why I think developers should be writing more about our most challenging bugs. Admittedly, part of the reason is my selfish desire to read more of them. At the end, I’ll share a few of my favorite stories I’ve read recently.
The Makings of a Good Story
I learned in my high school English class that a good story has exposition, some rising action, a climax, additional falling action, and a resolution. The best bug stories I’ve read follow this pattern too.
The exposition should provide the reader with context about the system that is experiencing the bug. In the rising action, we learn about the bug, the turmoil that it is causing, and the initial hypotheses. The climax is the eureka moment where our hero (you, the brilliant developer) saves the day by finding the root issue. In the falling action, we read about efforts to resolve the issue. And finally, the resolution wraps everything up and shares the big idea or moral of the story.
I find the most interesting stories come from seemingly mundane bugs that have unexpected or particularly bizarre resolutions. Other interesting stories come from highly complex systems that break due to weird timing or conversion issues. And more come from interesting investigation techniques rather than the content of the bug itself.
Teach and Learn
One of our values at Atomic Object is Teach and Learn. The clear benefit of sharing stories from bug fixing is to help spread the knowledge. It’s a true “diamond in the rough” moment when you’re researching an issue and run across somebody else’s blog or forum post describing the exact scenario. By writing about these experiences, we can help the community by dropping more diamonds into the rough.
Debugging is particularly tricky for many developers. That means learning new techniques from somebody who has climbed that mountain can provide invaluable second-hand experience. I also like using these stories to learn about other team’s architectures and technology choices. It’s often not possible to describe a bug hunt without describing the affected system in some detail. This is a great way to learn about other people’s practices and opinions. There’s also the benefit of reading about new or less common tech. I haven’t often needed to worry about CPU clock cycles in my day-to-day work, but learning how low-level concepts work to follow a bug investigation is very satisfying to me.
Entertainment
I find other developers’ bug investigations to be very entertaining. Oftentimes these stories read like true crime, with the criminal bug being investigated by an astute detective-developer. Other stories lean toward humor. I find these ironic because I know in my experience the hunt is anything but humorous. I suppose, in hindsight, it’s healthy to be able to laugh at your own circumstances. And, of course, sometimes a bad writer writes a dry investigative report, but even these can push you to think in new ways and find your own entertainment in the exercise.
Deeper Understanding
Another value I find in writing about bugs is that it forces me to digest and communicate what’s really going wrong. Sometimes it can be easy to hand-wave over the core issues and jump to the fix. However, when you need to communicate with people who aren’t in the loop, it requires a deeper understanding of the systems. This is a great way to organize your own understanding so that you can communicate clearly with the team in the future.
As a reader, there is value in being able to be comfortable with incomplete information. An author can’t provide full context, and often these sorts of stories take place in unfamiliar or new paradigms. Being comfortable in these unknown situations while still taking the time to grasp the core concepts is great preparation for scenarios like ramping into a new project or integrating with unfamiliar tech.
Writing About Bugs: My Favorites
I’ve found my love for bug stories by reading some great ones. Admittedly, I’ve done a bad job of writing about my own bugs in the past, but I intend to do more of that in the future. I’ve discovered most of my favorite stories shared on Hacker News or Twitter. Here’s a short list of reads I highly recommend.
- A chronicle of troubleshooting an issue in a GameBoy Advanced emulator. This is also the reason the phrase “invalid memory access” makes me think about Hello Kitty.
- A more recent story that gets into the weeds of an incident that caused an outage in the UK’s air traffic control systems.
- A story investigating issues in early XBox prototypes and unexpected external factors.