Keeping a debugging journal

A particularly fine example of a bug journal (not exactly a debugging journal) is the one kept by Donald Knuth for his TeX typesetting system.

The list is at http://texdoc.net/texmf-dist/doc/generic/knuth/errata/errorl...; the fairly long and very interesting paper he wrote about it ("The Errors of TeX") unfortunately doesn't seem to be freely available, but there's a very short informal article (also by Knuth) about it at http://www.tug.org/TUGboat/tb10-4/tb26knut.pdf.

He classifies all the errors he's ever found (or had found by others) into 15 categories. (Here "errors" includes "enhancements found to be a good idea", just as in many issue-tracking systems.) In the full "Errors" paper he has much to say about each category, including concrete examples and more philosophical ruminations.

I started keeping a development journal when I found myself getting interrupted quite a bit more than usual. It turned out to be very helpful but somewhat tedious to maintain at the level I would have liked.

I had some ideas about how to write software to automate some of the tedium and how great it would be if there were a large scale system that many developers used for tracking their work. If this system existed it could compare and contrast techniques and approaches used by more productive developers and help guide less productive developers down the path to improved productivity.

It seems like it would also provide a pretty good automatic Stack Overflow like experience in terms of being able to search for error messages and find the steps others had taken to solve the same problems.

I've found it to be really helpful to keep a project work log when working alone. Mine are very verbose and help the most at the time of writing, since it keeps me on task and solidifies ideas.

My friend does the same thing, here's what he wrote about it recently:

http://blag.cammunism.org/blog/2013/11/14/programmers-log/

Can you share your debugging journal? I have been thinking about keeping one, just to try see if there are patterns amongst the bugs I inadvertently write. There are indeed patterns and classes and categories of bugs, and I think that knowing them might prevent me from making the same (stupid) mistakes in the future.

I keep two text files open at all times: CurrentTasks.txt gets every new assignment and idea, sorted by priority order, most important stuff at the top.

Logbook<Year>.txt gets a date stamp every day, and collects the notes I take/leave myself as I go along, including any interesting command lines I won't remember later. I throw in any interesting error messages and other things I know I won't remember in detail.

Periodically, I'll garbage collect CurrentTasks and move the good intentions and other things I won't likely do over to the Logbook.

This is a corruption of David Allen's 'Getting Things Done' system, but it's worked well for me for years. I can't count the number of times the Logbook has acted as a ready reference for solving some obscure, occasional challenge.

I like this idea. Would anyone find interest in a mini-site for programmers to talk about how they've squashed bugs? Sort of a mini-social network I suppose.

I think this is a helpful action in some cases as well. Especially on teams where its less of a bug and more of a FAQ. Various questions about an application that are common and where to look for the answers. Saves everyone time.

For actual bugs. A lot of times they are one off, but if it is say an issue with a configuration or deployment that could come up again I definetly see the value there.

Why not use GitHub? You can file and look up commit histories, write comments, track Issues/bug reports, collaborate with others.. all in one place.

If you want a public debugging journal for a private or self-hosted project, I think Evernote combined with http://postach.io would work beautifully.

I've created my own MoinMoin (FOSS python wiki) instance primarily for keeping a development journal (http://wiki.juanl.org/DevLog).

I usually try to capture anything that I spend a significant amount of time figuring out.

The fact that it's a wiki makes it great for organizing other ideas too.

So much truth! I've been keeping one myself for the past ten months and it helps immensely when switching between projects all the time. I don't use a blog or evernote but a set of scripts I made, it's an excellent use case for Dropbox too.

Yep, and if you post it to say tumblr, or your blog then people searching for the same problem you have will also run across it.

Great way to help others, and keep the "Just Google It!" mantra alive.

are there any sources we can go for explicitly for making some kind of debugging journal?