Keeping a Worklog

2021-08-28

I keep engineering notebooks for a lot of my projects; I usually call the file WORKLOG. A low-formality text file, kept with the project source, is a handy place to keep links and logs; and verbalizing my thought process helps me progress. I’ll likely share some (edited) worklogs here.

Some more thoughts and background:

Incident logs, bug reports

My first job included [on-call] responsibilities. For a few days out of every month, I was be the first point-of-contact for any indidents in my team’s portion of the production systems. Our team was split between continents; at the end of a 12-hour shift, we would send a written hand-off to the next oncall.

For these hand-offs, I got in the habit of writing up just about everything about the incident: what we knew, what we thought, what we tried. I kept this up when not on call; recently, one of my coworkers thanked me for the “book” I wrote in response to a bug report.

Worklogs

I took this habit home with me- and to a greater extreme. Most of my personal projects have a plain-text file checked into source control, in which I write up:

I usually call this file WORKLOG.md, but the idea is similar to an engineering notebook or engineering journal. In software engineering, source control forms some of this record- the path taken. A journal forms a useful supplement, including roads not taken and the rationale for those choices.

Even for projects I never intend to share or publish, I find it useful to keep a worklog. It’s the same effect as a [rubber duck]: verbalizing my thought process can highlight gaps.