Engineering Notebooks: High Level Thoughts and TDD To Do Lists

Ever since I was in college as an electrical engineering student, I’ve been advised to have an “engineering notebook”. The general recommendation was to have a single place where you wrote down all the important details of your work. In the case of circuit design, dated notes could be particularly important for establishing prior art in patenting intellectual property. However, since my career was headed in the software direction and software patents were not yet common, I didn’t give it much thought. As my career progressed, I found I had two kinds of information that I needed to write down as a software engineer: notes from meetings and design discussions and low-level task details related to the code I’m working on day-to-day. In this post, I’ll discuss a simple system that I’ve adopted for engineering notebooks that makes sense for software engineers practicing test-driven development (TDD).

For a long time, I was just taking meeting notes on a notepad that was roughly annotated in chronological order. If I needed notes for a complex software task, I just took those notes on a piece of scrap paper and discarded the scrap paper when the task was finished.

Years later, I read Kent Beck’s “Test-Driven Development By Example”. In this book, Kent recommends keeping a running “To Do” list as you progress through a task. The idea is that while you’re working on one thing, you’re likely to notice something else that also needs doing. You may also encounter something smelly about the code you’re modifying that could be improved later. The idea of the “To Do” list is to stay focused on the current task, but at the same time make note of other things you might need to do. Once you finish the current task, you cross it off the To Do list and pick the next thing off the list that seems most important.

Once I started practicing TDD, I noticed that I was accumulating a To Do list on a notepad and that when I came into work on any given day, I always knew what to start on because I had the To Do list to consult. Because the list grew organically from the immediate work that I was doing, it rarely had items on it that were irrelevant. Sometimes there would be items of a refactoring variety that would be deferred, but mostly it was full of the details of the story that I was implementing at the time. I still needed to take notes at high level design meetings, product planning sessions, and so-on. Mixing these in my To Do list was problematic because I wanted my To Do list to be like a terminal screen: once something scrolled off the top of the page, it didn’t matter anymore. If I intermixed meeting notes with my To Do list, then I would have items on my list that I couldn’t cross off and it would be hard for me to find them again as I’d have to skim through many pages of crossed-off items in order to find it again.

I decided to take a single notebook and write in both ends of it. Meeting notes and high-level design ideas would go in the front, written only on the right side of the notebook and would be dated. The To Do list would start in the back, written only on the left side of the notebook, and would also be dated. I made a conscious effort not to be frugal with the space in the notebook. I would write in big writing and not worry about wasted space between entries. This meant that I would always know where I was by a quick glance at the notebook. Eventually, the two streams of annotations meet somewhere in the notebook and then that notebook is retired and new notebook started.

Not being frugal with the space in the notebook ended up being important for another reason as well. These notebooks have simple bindings on them that don’t stand up to prolonged wear and tear. If I wrote too small and was too frugal with the space in the notebook, then it would physically deteriorate. If it was a glue binding, pages would start falling out of the binding; if it was a spiral binding, then the spiral binding holes pages at the front and back would start to open and the pages would break free. Paper notebooks are not expensive and it doesn’t make sense to be so frugal with them that they physically deteriorate before you consume them completely. Even with my wasteful approach, the notebooks tend to fill up after 12-18 months.

With this method, I had all my information in a single place and I never needed to look for any scraps of paper. If I was in a planning session and a question came up about when something was implemented, I could quickly scan my crossed-off To Do list and associate it with a date. While in release planning meetings or other meetings, I had all my notes from previous meetings together in one chronological place and I could see when release dates or scopes changed.

After I adopted this system, I recalled being in meetings years earlier where representatives of Franklin-Covey, a local company, advocated the use of their day planners. They basically had something similar in that they had a “To Do List” portion of their organizers. However, when I tried that system, I found that invariably there would be uncompleted items on my To Do list and the Franklin-Covey system told me that I needed to copy them from the previous day onto the next day’s To Do list. I found this to be tedious and repetitive to be mindlessly copying items from one calendar page to another, so that system never took root with me. Their system also had many aspects that I simply did not need. Granted, they were advocating a system of time management and not a system for engineering notebooks, but I found the whole thing to be overkill and designed around selling me day planner supplies more than actually solving any of my problems as a software engineer. With the notebook approach that I adopted, it doesn’t matter how many days have passed since the last time I added or completed an item on my To Do list, the remaining items are always shown to me at the end of the list and the done items are crossed out.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: