Getting Organized with an Engineering Logbook

About year-and-a-half ago I read a short post about logbooks, journals kept by engineers to log their thought process, break down problems, and find ways to improve.

As a software engineer, it is easy for me to get caught up in the romantic idea of following "normal" engineering best practices, but the post also caught me at a good time. I was becoming a tech lead on more projects and found myself getting pulled in a lot of new directions. I was primed for the idea of a logbook: something to help me track my daily work and mitigate the cost of context switching. 

Since that time I've found logbooks to be a powerful tool that help me to reflect on my work, be more engaged in meetings, and get back into the groove of production work after a mid-day distraction.

I never want to go back.

What does this look like?

Going back to my original inspiration:

1. Consider the problem you’re attempting to solve
2. Describe your method for solving it
3. Describe the process of carrying out the method
4. Record what happened, and ask how it could be improved

I don’t think it’s necessary to follow these steps exactly, but they are good goals to keep in mind. I usually end up with something more like:

1. Write down a task
2. Close Slack/email
3. Work for a period of time (like a 25 minute pomodoro)
4. If the work wasn’t completed, why? Can it be broken down?
5. Write sub tasks
6. Check Slack/email
7. Rinse and repeat

The actual steps don't matter, it's really more about carving out "buckets of time"

Really, with whatever process you follow, you want to optimize for three types of activities:

• Focus. Deep work is real. Working on a programming task with 100% full attention is bliss, but that must also be weighed against being a responsive teammate.
• Reflection. Things can always be made better, and some problems need to be broken down further. Sometimes, to move forward, we must look back.
• Distraction: Communication with your team and company are essential, however it can be very distracting. Make time for it so that distraction adheres to your schedule.

Use paper, a text editor, vellum, whatever medium you can stick with

For the first few weeks I used pen and paper; however I found myself wanting to search and copy/paste things into Slack, so I moved to my text editor. As an Emacs user, I use org-mode, but really you just need something that can record text.

Starting a day

I start my day with a basic outline:

I keep these in a folder on my computer that I back up on Google Drive. After doing it more than a year, it is incredibly useful when writing my self-review and looking back on what mattered to me at a given time. Pretty neat stuff.

Making the most of meetings

If I don't catch myself, I'll go into a meeting blind, so most days I start by jotting down the meetings I have on my Google calendar. Yeah, it’s duplication, but most meetings have an agenda with questions or something else that requires prep work anyway. 

This section gives me a great place to jot down notes and follow-up items:

As a remote worker, it is easy for me to keep my notes up along side a video conference. For in person meetings, I try not to bring my computer into the room and write down anything crucial on a notepad for later.

Add meta data when you can

This will depend on your recording method, but I can add meta data like timestamps (seen above) next to a note, making it visible in a special agenda generated by org-mode:

Pretty cool right?

Tracking and breaking down tasks

org-mode can also track the TODO keyword, so I use it to keep track of dev work. Ultimately, the source of truth for this stuff is my ticket tracker, but jotting down all of my stray thoughts on JIRA or Github Issues would be miserable for my team.

So whenever I start on some work, I jot down a TODO:

Then I get to work. I try to follow the pomodoro technique whenever I can. I love it because it forces me to stop, really think about what I did, and what I need to do next. I'll chew on a task for about 25 minutes and then take a 5 minute break to reflect, answer an email, or take the dog out. 

Seriously: don't skip the in-between time. This is a great opportunity to write down challenges while they're fresh, follow up with that knowledge on tickets, and bring issues to the team. Often that will turn into additional action items that you can follow up on in the next 25 minute work session, or avoid a lot of work if it turns out the effort isn't worth it.

For difficult problems, I'll break up the work into more TODOs that are nested under the first:

And then I keep going. At any point in time, I might have to shift gears to something else, but my next steps are clearly laid out. I can also schedule out reminders to check at the end of the week so that any outstanding tasks haven't fallen through the cracks, and if a stray thought hits me during focused work, I can circle back to it later.

That’s it. I've found it to be surprisingly fluid and effective.

Why it works for me

Leaving myself breadcrumbs makes it easier to shift gears. If I have to pivot to review some requirements, jump into a meeting, or take a break for lunch, I've laid out clear steps to pick up the work later. By keeping to 25ish minute chunks, I avoid holding too much in my head.

Progress updates in meetings. It's much easier and productive to convey challenges when you've thought about them ahead of time. Often this leads to modifications to a design that greatly reduces dev time, or at the very least greater empathy.

Durable storage is an essential part of good reflection. At least for me. Often at the end of the day or a long sprint of work, I need to clear my head before moving to another task. Writing things down makes it easier to move on and review things later.

What works for you?

That's my flow. I don't think it's the "one true way", but it works for me. If you do something similar, or are interested in the idea, I'd love to hear your thoughts!

Bonus: here are my Emacs functions for generating a workbook for the current day. Have fun!