David Golden, one of the reviewers for Intermediate Perl, gave me extensive comments about one of the test program examples in the book. I made a simple example using Test::Output, a module I sometimes use but didn’t write. It solved my needs at the time, but it has some issues. Perl’s output is complicated, and the simple tie in Test::Output::Tie doesn’t cover all the cases.
I’m the current maintainer of the module, and rather than explain the edge cases in my example (or fix the module), I merely mentioned to David that we should reimplement Test::Output with Capture:Tiny, his module that handles almost all cases. I meant “we” in the universal sense, and I didn’t say much because I was busy writing the book. A couple of hours later, David sends me a pull request.
That often happens as part of the writing process. If something is too hard to explain, it’s probably too hard to use. The time explaining it is better spent making it clear, unbuggy, or whatever it takes to avoid the explanation. In this case, it’s even better when someone else did it.