The Pocket Guide to Debugging: 47 Strategies in a Zine

Julia Evans has released a new zine, The Pocket Guide to Debugging, collecting 47 strategies for tackling stubborn bugs. It's available for $12 from wizardzines.com, or as part of a 12-pack of all zines.

A Table of Contents That Stands Alone

The zine's table of contents doubles as a standalone reference, laying out the strategies at a glance. Printable poster versions are available for those who want to keep it on hand:

Debugging Is a Skill Nobody Teaches

Evans wrote the zine because debugging consumes a large share of programming time, yet it's rarely taught directly. Pair programming with an experienced debugger is one way to learn, but not everyone has that opportunity. The zine aims to teach strategies explicitly, giving beginners a structured path and serving as a reference for experienced programmers stuck in the middle of a tricky issue.

Companion Debugging Mysteries

The zine comes with interactive debugging mysteries, presented as choose-your-own-adventure puzzles at mysteries.wizardzines.com. These walk through the strategies in practice, focused on networking bugs, and demonstrate how to interpret output from common networking tools. Notes on building the puzzles are available in an earlier blog post, Notes on building debugging puzzles.

The Zine Works on Its Own Author

Evans reports that the zine has been surprisingly effective even for herself, despite knowing all the strategies already. In the middle of a frustrating bug, she finds it helpful to pull up the table of contents and find a new tactic to try. A recent CSS bug, for instance, was resolved by forming one small question, writing a tiny program, drafting a help request, and then checking the docs — before discarding the unsent message.

Making the Advice Specific

The biggest challenge was going beyond broad advice like "reproduce the bug" or "be rigorous." The initial draft read as generic guidance, so Evans spent six months working daily with Marie Claire LeBlanc Flanagan to convert each guideline into concrete actions. Beta readers, 40 of whom reviewed the draft, provided substantial feedback that shaped the final version.

Related blog posts on debugging were written during the process:

As with previous zines, home printing is possible. The Pocker Guide and has a non-standard size — twice the length and half the height of other zines — so the print copy requires cutting in half, marked by a dotted line. Full instructions are available in a print directions video.

A new option is available this time: a physical print copy can be shipped. Orders placed via the "print version" link on the zine page will ship around the end of January, after the print quantity is decided based on order volume.