Debugging Notes a la Mystery Novella

I’ve always been a huge proponent of taking really good notes on what I do in a day. I think that daily note taking, and journaling in general, is one of the most impactful practices in my life. It gives me an easy way to look back through what I was thinking about, what I thought about it, and a way to track new things going forward. I’ve changed up my methodology over the years, but I stand firmly by writing a bunch of words throughout my day being just crazy useful.

One of the most useful types of note taking I do is when I’m debugging an issue. It can work well in other areas, but it’s a lot of fun when you’re fixing a bug. The whole trick is to treat the process thing like you’re writing a story. I specifically like to imagine that it’s a sort of mystery novel where I’m the detective tracking down something unknown. It gives you a structured game plan for debugging, it forces you to think through all of the bug’s implications, and it gives you a great piece of documentation at the end. Ideally, someone reading your document will be able to completely understand the bug and would be able to debug it themselves if it came up again. I’ll outline more specifically what I do, but really that’s the whole idea.

My method is simple:

• Create a document with headings for each of the five elements of a story.
  • Exposition - what is the bug? How did you notice it? When? Is something behaving differently than expected? Ideally, everything you know about this bug when you first sit down to debug it makes its way into this section.
  • Rising Action - is where you start the real debugging. The Author Learning Center says that rising action “normally begins with an inciting incident, or a moment that sets your story into action. As it progresses, you’ll have multiple moments of conflict that escalate and create tension as the story moves toward the climax.” This is where you’ll record the twists and turns of actually figuring out what’s going on. A good sign that you’ve completed the rising action section is that you’ve finished writing a failing test case that, once fixed, means you’ve resolved the bug.
  • Climax - is where everything changes from “what’s going on” to “let’s fix it.” This is when you can definitively say that you have tracked the issue down and know how it’s failing. I like to treat the climax as me actually fixing the bug. We’re writing code, we’re running tests, we’re documenting what does and what doesn’t work. This is your chance to record the decisions you’re making and why you’re making them. At the end of this section, your test case is passing.
  • Falling Action - is where you stop and assess the fix itself. In this phase, we’re going to make sure we’ve thought about any second-order consequences that either the bug itself or your fix will cause. Write out anything else that might be needed for the bug to be fully fixed. For example, many bugs at SBLive will have affected dozens of games before we’ve found and fixed it, and in those cases I typically also need to write a rake task that can be run to programmatically fix those previously affected games.
  • Conclusion - is where you wrap everything up. The whole document you’ve created is really just a living incident post-mortem, but the conclusion section is useful for recapping how everything actually ended up turning out. Imagine that this is the only section that most people read.
• I usually also have a separate “Questions” section in which I just keep a running list of questions I come up with during debugging. This section is useful when it feels like I’ve hit a dead end or when I feel like I’m missing a link somewhere in the chain.
• Starting with the exposition, start filling in each element with the pertinent information about your bug.
• Once you’ve fixed the bug, go back and flesh out the sections to fix any typos and add any new findings that you now know were relevant. I try to keep this step pretty minimal — part of the point of the process is that the reader learns everything along with you — but it’s important to help take it from “rough notes” to “fun story.”