This is something I do when I'm working on a hard or perplexing bug. I'll write down a verbose description, as if I'm describing the bug to someone, or having a conversation with myself. I include all the debugging data I find, as I come up with tenative hypothesis, write them down, as I disprove them go on to say why that hypothesis failed, etc.

I just dealt with an OpenID signin bug in ikiwiki, which ended up being several hundred lines of text descibing my process for solving the bug, including amusing blind alleys involving a sha1sum implementation being broken (it wasn't).

And then I committed the one line fix, and :q!'d out of the buffer containing my bug solving log, because all that text now seems both boring, and, given the cause, embarrasing..

Anyone else do that?

It has its good and its bad points. I suspect most of the time that I spend typing into the log, I'm also spending organising my thoughts, and it makes sure that all relevant debugging information is all in one place and well organised to look at, and avoids me looping back into blind paths that I've visited before. On the other hand, I could probably go read a book (or in some cases, an appropriate man page :-/) or sleep and process the bug in the background without all that typing.

discussion