
Keeping a debugging journal - steverydz
http://steverydz.com/2013/11/19/keeping-a-debugging-journal/
======
gjm11
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...](http://texdoc.net/texmf-
dist/doc/generic/knuth/errata/errorlog.pdf;) 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](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.

~~~
a_bonobo
You have a slight typo in that first link, HN interpreted the semicolon as
part of the link, fixed:

[http://texdoc.net/texmf-
dist/doc/generic/knuth/errata/errorl...](http://texdoc.net/texmf-
dist/doc/generic/knuth/errata/errorlog.pdf)

~~~
taspeotis
This one stuck out for me:

    
    
        * Time sharing is very slow today, so I'm mostly reading technical reports while
            waiting three hours for compiler, editor, and loading routine.
        * I'm not counting this as debugging time!
        * (Came back in the evening.)
    

For reference, you can compile the Linux kernel in as few as eight minutes
[1].

[1] [http://askubuntu.com/a/244148](http://askubuntu.com/a/244148)

~~~
a_bonobo
By time-sharing, does he mean sharing computing time on a cluster? I work on
my university's cluster and on bad days, my jobs are queued for 4 hours and
then run for 20 minutes...

~~~
pseut
Dude, you didn't even look at the pdf did you. That was the entry for _13 Mar
1978_

~~~
a_bonobo
I'm pretty sure clusters changed in their architecture and their processing
power, but you still have to stand in line

~~~
timtadh
In 1978 Time Sharing Machines refers to single machines with multi-tasking.
ex. the terminal you are using right now. So you don't have to "wait in line"
you have to share resources. Just like your web-browser shares resources with
your editor.

[https://en.wikipedia.org/wiki/Time-
sharing](https://en.wikipedia.org/wiki/Time-sharing)

esr also has a good article:
[http://catb.org/jargon/html/T/timesharing.html](http://catb.org/jargon/html/T/timesharing.html)

------
lgas
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.

~~~
steverydz
That sounds like a great idea!

------
jewel
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/](http://blag.cammunism.org/blog/2013/11/14/programmers-log/)

~~~
ibash
I do the same thing, but not just when working alone -- I just use a a text
file in dropbox + vim.

For more complicated tasks I create check lists before hand (to make sure I
cover the edge cases), and sometimes create "Testing:" check lists to make
sure I also test all the edge cases. I also have free form text when I'm
thinking about a problem, or when I get feedback about different things.

It's organized by day and is invaluable, with a simple search I can find out
what I worked on any day -- really good for reflection and marking progress.

------
daniel-levin
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.

~~~
steverydz
I just started it this afternoon but do intend to share it once it fills up a
bit. I'll update the post when I do this.

------
pjmorris
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.

------
dpedu
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.

~~~
kayzee
StackOverflow contains a list of documented "bug fixes". and I bet most devs
find their solutions on SO anyways.

I find this suggestion more valuable within a medium-large company. An old
employer of mine had a "Trouble Call" reporting system where you submit a
problem/solution and can search the DB later to help with repeat issues.

------
leerodgers
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.

------
rohamg
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](http://postach.io) would work
beautifully.

------
jlas
I've created my own MoinMoin (FOSS python wiki) instance primarily for keeping
a development journal
([http://wiki.juanl.org/DevLog](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.

------
hobo_mark
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.

------
thejosh
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.

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

