Engineering Daybooks

A few months ago I read the excellent 20th anniversary edition of The Pragmatic Programmer by David Thomas and Andrew Hunt, and one of the tips I put in to practice right away was to start keeping an engineering daybook.

My Daybook

My daybook is a physical notebook that lives on my desk, and as I work I jot down any little details that seem relevant to my current task - things I need to do, notes on how a component or function works, reminders to go back and undo values I’ve temporarily hard-coded, that sort of thing. David and Andrew recommend using pen and paper for this, and I’ve found it helps separate my “stream of consiousness” note-taking from more organised and longer term digital notes.

An engineering daybook acts as a little store for details that’ll quickly get lost over time. When someone asks how you solved a problem you had several months ago, you might only vaguely recall the issue and how you solved it. Being able to flip back through your daybook and give a more accurate answer refreshes your memory of the lessons you learned solving the problem and allows you to be much more helpful.

I started keeping my daybook in March, and today it really came in to its own.

Old Ticket, Forgotten Problems

My team is curently running an exercise in reassessing how we estimate tickets. We’re taking all the tickets we’ve completed over the last couple of months and shuffling them around in order of the amount of work they ended up taking, and comparing that to the original estimates we gave them to get an idea of how accurate our estimates are. Did the small tickets end up being small? Did the big tickets really take much longer to complete than the small ones?

A ticket I worked on a few months ago is an outlier - we estimated it as needing an average amount of work but it ended up taking longer than expected. What happened? Why did it take so long? I remember it being troublesome and having a few unexpected complexities that only came to light after work had begun, but I couldn’t remember exactly what those complexities were or why they’d resulted in delays.

I was able to check the dates on the ticket and flip back to that time in my daybook, and there it all was - a collection of unexpected problems, notes on my thought process as I debugged and puzzled my way through them, and the solutions I arrived at. With a refreshed memory of exactly what I’d done, I was able to make recommendations on how we might avoid similar problems in future by refining our tickets in a little more detail upfront.

Perhaps some of the unexpected problems I encountered would have been surfaced with a bit more of a deep-dive in to parts of the codebase I’d be touching before we marked the ticket ready and pulled it in to sprint. Perhaps we could have broken the ticket down in to smaller tickets and shipped the work in multiple iterations instead of all at once. I could make these suggestions for improvements to my team’s process because now I remember those months-old details like I’d solved the problems yesterday.

Try Keeping a Daybook

This isn’t the first time keeping my engineering daybook has paid off, but I think it’s the most valuable so far. Try keeping one for a month (or longer!) and see if it’s useful to you. I’m convinced of the value of jotting down every little challenge and solution as I go, and I plan on filling notebooks for years to come.