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:
- Problems / issues; log messages, errors, etc.
- Hypotheses, tests, and solutions
- Commands or external actions that don’t make it into source control, e.g. package installs
- Useful links and references
- Useful lessons or discoveries
- Alternatives considered, tradeoffs, and decisions
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.