Joe's
Digital Garden

Software Engineering Labbook

The notion of a Software Engineering Labbook or just Labbook is to produce a log of work over the course of a project or day that details what work was done, when it was done, and what work remains or was created by that work. It builds on the syntax of [[Bullet Journals]].

I maintain two labbooks, one for work and one for side projects. Each is a Leuchtturm 1917 bullet journal with the first few pages kept as an index and all subsequent pages after being the running log. Although, the workflow is also easily adapted to a simple text file.

Each spread in running log has a horizontal row across the top containing: 1) a title for the work conducted on these pages and 2) The date when the spread was started. Each page has a four-square wide column on the right where dates and times are recorded. The remaining space is kept for logging entries.

The process derives from Kent Beck's Test Driven Development. I begin each day my marking the change of day in the left column and the time.

Add Post Module                                                 2020-10-20 
---------------------------------------------------------------------------

10-20   |
--------|
0900    |

Next, I write down the task that I am embarking on as a bullet:

0900    | • Add a post class

When that task is completed. I mark it complete and then add another bullet for the next task. The key is to write down what you are going to implement before you embark on implementing it.

0900    | x Add a post class
0915    | • Write a unit test for post publication

As I am working a task, I might add notes to reference in the future using the - icon or if my work has created additional orthogonal work, I can add them using the + icon.

0900    | x Add a post class
0915    | • Write a unit test for post publication
        | - Note posts are not organized temporarily
        | + Posts should have an author; add an author class

If old notes or additional tasks are rendered irrelevant, then I can strike through these tasks to remove them. Notes can become elaborate including diagrams and whole paragraphs. I can also use the circle ("◦") icon to represent scheduled events such as meetings:

0900    | x Add a post class
0915    | • Write a unit test for post publication
        | - Note posts are not organized temporarily
        | + Posts should have an author; add an author class
        | ◦ Meet with product to discuss author properties @1300

When I complete the current bullet that I am working on, I can either add another bullet for my next task or I can migrate one of my new tasks into a bullet:

0900    | x Add a post class
0915    | • Write a unit test for post publication
        | - Note posts are not organized temporarily
        | > Posts should have an author; add an author class
        | ◦ Meet with product to discuss author properties @1300
1000    | • Add an author class 

I migrate a task by writing over the + with an > and then adding a new timestamp and bullet for the new task. This allows me to quickly look over the log and see all outstanding tasks since any + or icon that has been neither completed, struck through or migrated is still outstanding. Scheduled events are handled similarly.

If a blocker arises, I stop work on my current bullet and add a new timestamp and bullet for the blocker, then switch to working on the blocker:

0900    | x Add a post class
0915    | • Write a unit test for post publication
        | - Note posts are not organized temporarily
        | > Posts should have an author; add an author class
        | ◦ Meet with product to discuss author properties @1300
1000    | • Add an author class 
1015    | • Create the author table

When the blocker is finished. I migrate the original task to a new timestamp and bullet:

0900    | x Add a post class
0915    | • Write a unit test for post publication
        | - Note posts are not organized temporarily
        | > Posts should have an author; add an author class
        | ◦ Meet with product to discuss author properties @1300
1000    | > Add an author class 
1015    | x Create the author table
1045    | • Add an author class

Note: This is a running log for the day. So pages are not seperated by project. If a hotfix arises, and work must shift to an entirely different project then that is just treated like a blocker. Add a new timestamp and bullet for the new work. Complete that work. Then migrate the task placed on hold when work resumes. It is concievable for lots of tasks placed on hold to never be resumed, be striked, or simply pile up as a backlog. The point is if that task is ever resumed, we can run back through the log to when that task was placed on hold to see what work was done leading up to that hold.

As you can see, the log allows me to quickly assess what work I was doing at any part of the day, what work remains outstanding. And when I begin a new day, I can quickly assess where I left off.

External References

  1. Beck, Kent. Test Driven Development: By Example. O'Reily, 2002.

Linked References