http://qs321.pair.com?node_id=141369

In this meditation, I recommend keeping a technical diary.

A diary is usually literature written to be read by the author. As its Latin name implies, its contents are arranged by the day's date. Ideally, a diary tracks every day's events. Entries may be very brief or extended; they may reflect the summation of a problem satisfactorily solved or as likely, they may record failures, or be used to freeze-frame an incomplete thought; they may be highly personal in nature, or not. A diary records what the author wants to read.

An entry in a diary expresses thoughts that are in some stage of taking form, it is a glimpse of the author's state of mind while making way through the unmarked paths of new experience. The author's understanding is the work in progress described by a diary, and so, a diary entry is rarely a work ready for publication. A diary isn't kept with the primary purpose of publishing its contents - in fact, the effectiveness of the diary technique will be significantly affected, probably hurt, by the prospect of others reading the material. It may be private and random, or it may be more polished journal-type literature but, whether the journal is ever read by others, is the author's choice. It is material written for oneself.

I use a diary technique myself, for technical issues, especially when I begin to struggle while learning some new thing. I start making entries when I seem to be having trouble thinking through a problem clearly, and especially when I find I am stumbling, fumbling with the same or similar solutions repeatedly but making little progress. I prefer to keep separate project diaries, even though I usually don't make more than a couple entries in any of them each day.

Here's a sample entry from my 'dbi_diary.html' (It's not necessary to sign every diary entry as '**sigh**.' but I usually do.):


Wed Jan 16 10:02:39 PST 2002
found in /root/.cpan/build/DBD-mysql-2.1010/t/dbdadmin.t

test uses the perl library lib.pl, which is found in the
same directory. I copied them both to my ~/bin directory.
To set up dbdadmin.t to run outside of the test directory,
lib.pl is happy to accept environment variables, or just
let it run with its defaults.
$ perl -we '
BEGIN{ $ENV{DBI_DSN} = q(DBI:mysql:database=test);
$ENV{DBI_USER}= qw(root);
$ENV{DBI_PASS}= "passwd";
}
do "/usr/home/markmc/bin/dbdadmin.t";
######### RESULT >>>>>>'
1..20
ok 1
ok 2
ok 3
ok 4
Segmentation fault (core dumped)

**sigh**.

Thu Jan 17 09:04:00 PST 2002
I removed the password for my mysql root, and the problem went away.
Curious thing:
the login was correct, but mysql resources weren't being listed. The
seg fault was caused by attempting to work on an empty list.
Some sort of privileges issue, I think - something affecting
logins via DBI but not via mysql shell.
Curiouser thing:
The problem doesn't affect system user 'root', regardless of mysql login
(as long as the login is correct, of course).
That ain't how it's s'posed to work, is it?

**sigh**.

Even if each day's entries appear to be a record of defeats when they are written, they may obtain a very different aspect when they are read again, later. For someone of a more self-assured temperament, the effect may be the opposite of mine. I like that about the diary technique. It provides a view over the backyard wall, a survey of problems I dealt with in the neighboring previous days, together with an insight into myself and the way that I work, as I recorded my thoughts in the midst of the experiences - otherwise only unsympathetically and imperfectly recollected. It's a record of what has been learned or what remains to be understood, and even of what has been forgotten.

If you've never used a daily journal for working through technical problems, I hope that this meditation makes the idea sound interesting to you. I think you will see immediate benefits from giving it a try. For many technical people, it's an indispensable tool; but, most of them very likely use a diary differently than I have illustrated here. The ways of using it are as varied as people are different from one another.

I've also thought that a private journal could be a useful feature on this site - and at about the time I was giving thought to this, the Scratchpad showed up in the Monastery. I've noticed that some monks use their scratchpad in a sort of diary fashion. Maybe consideration could be given to a calendarized scratchpad - private nodes automatically indexed by date, that can be made public or stumbitted to SOPW, for example.

You monks who regularly use a diary technique as you work through problems, how have you benefitted? How do you use it? Please tell me what you think about diaries.
mkmcconn

Replies are listed 'Best First'.
Re: diaries useful
by spaz (Pilgrim) on Jan 25, 2002 at 04:58 UTC
    I'm currently doing technical support. I can't help but agree that a diary is very useful. I record what happened, what if anything I learned, and what to expect from a given customer in the future.

    I also suggest fellow monks use RCS or CVS with their diary. I also make a monthly tarball and copy that some place "safe". This data is very valuable to me and I'd hate to lose it.

    ++ for reminding me of how useful it is.

    -- Dave
Re: diaries useful
by snapdragon (Monk) on Jan 25, 2002 at 16:30 UTC
    I have to say that I think diaries are invaluable. I tend to use mine in a similar way to the way mkmcconn does; although I tend to jot down other useful information too (IP listings, bits of syntax that I *always* forget, etc).

    After reading this node I leafed through one of my diaries and I noticed that over the last year or so:

    • My code style has changed in quite subtle ways. Some of this is due to more rigorous design of code; but I think (hope!?) that I'm improving.
    • Some things never change. The amount of times I've noted down that I've done a UNIX installation on a server, set up a root password, installed the server in the rack and then walked back to my desk only to find I cannot log in remotely (there is no other user and root is not allowed direct remote log in) is quite scary. In fact after each time I've done this I've written something down (like "don't do this again!"). And yet still I continue.... must be a mental block I guess...
    • My writing now has a lot more code in it that before. I don't mean lumps of code; I mean using bits of code as abbreviations, or as syntax in their own right. Which makes sense to me but must look weird to anyone else.

    So what about the rest of y'all? Anyone else find bizzare bits of code in their everyday language recently? Or odd mental blocks that you just cannot shake? C'mon.... I can't be the only one...

Re: diaries useful
by weini (Friar) on Jan 25, 2002 at 15:33 UTC
    I started using Literate Programming for well documented and easy-to-read programs and CVS to get the various versions in some order. Writing a diary is another good idea to get your thoughts and deeds organized.

    I used to write about tech changes and problems as much as possible using plain HTML-Files I share with my collegues but I don't write a diary yet. I now consider starting one.

    Thanks for this input!