Why Every Engineer Needs a Work Journal & How to Maintain One

Have you ever found yourself feeling overwhelmed with tasks, struggling to remember what you did last week, or unable to effectively communicate your progress with your team? That's what the first few months of my Software Engineering career looked like, until I adopted the practice of a work journal.

A work journal is integral to stay organised, communicate more effectively, solve problems more efficiently, and gain a deeper understanding of your work. Plus, it can serve as a valuable documentation for future reference. I know it may seem like just another chore, but once you start, you'll wonder how you ever functioned without it!

In this article, I'll be going over the benefits of maintaining a work journal and the ways you can get started.

The Benefits

Time Saved

When you're onboarded onto a new company, team, or project, you're overwhelmed with the amount of information thrown at you at any given moment.

For example

• This is how our very specific undocumented internal tooling works
• Oh the documentation for this is outdated, this is actually how you do it
• Ah shoot! My dev environment is broken, there's this very specific command that fixes it but I forgot what it is!

The amount of Google Meets calls I've been on with fellow Engineers to help me out with something I should have documented ages ago is something I'm still quite ashamed of! Thankfully, my coworkers were rockstars that always helped me out.

So the next time you come across something that is unique, undocumented, or even just interesting, you now have a place to reference. You can also use your reference to publish documentation for the entire company on their knowledge systems (e.g Confluence).

Communication

Do you ever have those days where you feel like you've achieved nothing, and standup is quickly approaching? In reality, you should be documenting all your ticket work inside your journal, even going as far as to outline your thinking! This can help immensely.

If you've spent awhile working on a bug, you still have your thought process outlined, for example,

ticket dev-540
assigned date: Tuesday 3rd January 2023
link: piedpiper.notjira.com/dev-540

Problem: The endpoint /someCoolFeature is returning null

Solution #1: Is the JSON in the right format?
Outcome: Didn't work 
- Checked the JSON data being sent, looks ok

Solution #2: Does the SomeFooBarDTO.java class have a bug in it?
Outcome: Working on it
- Run the test suite, what happened? 
    - Result: The test suite passed
- Go through the related classes

Now at standup instead of saying,

Oh I've been working on dev-540 but I haven't found a solution yet

You can now say

I picked up dev-540 on Friday after standup, the issue is the endpoint is returning null for some reason, I checked the JSON format but it seems to be right, otherwise I've run the test suite on the class it's in "SomeFooBarDTO.java" but it seems to be okay, I'll be going through the related classes. I think the solution is in reach, so I don't have any blockers

Now your team knows exactly when you started working, what you're doing, your thought process, and how far along the process you are.  

This bit goes hand-in-hand with an awesome video Rahul released not too long ago about giving great standup updates!

Career Growth

Additionally, you can use your journal to document your 1:1 meetings, gather feedback, or even highlight something you've noticed is undocumented.

If you're consistently going through these notes, you can start to rapidly iterate on your feedback, and plug gaps within your team no one else is noticing. Needless to say this is amazing for career growth, and it covers 2 of the 3 key traits of fast growing Engineers, that Rahul discusses in the following video

Another key part of your journal should be a "Brag Document" this is where you outline key things you've done with your time in your team or company. This can be pivotal when edging for a promotion, or switching companies. Your Brag Document should contain everything, no matter how trivial, in how you've positively impacted your team.

How to create & maintain a work journal

Productivity systems are highly personal, my specific setup is a single markdown document I access using my terminal and edit via neovim. The markdown document uses the philosophy from OBTF (One Big Text File).

Here's an example of how I maintain mine. I write things as I go, and at the end of the day I organise what I need to get done for the next day.

There are endless possibilities when it comes to maintaining a work journal. You can use a variety of apps (be sure to check your company's software policy!) and methods to maintain it such as

• Bullet Journalling & Getting Things Done (Evernote, Bear, OneNote)
• Knowledge Graphs (Obsidian)
• Kanban (Trello, Notion)

The list of productivity apps and methods that exist in this space is vast.

My general advice for setting up a productivity system would be not too get too carried away in organising it and making it look appealing, but to focus on three key pillars

1. Quick Capture

This is specifically why I use markdown, I live inside the terminal anyway, so when I get information in a meeting, all I have to do is get into insert mode. However, this might not work for you, for example if you're a Frontend Dev my system in neovim won't be as frictionless for you, because a lot of your work might have wireframes which would be easier with a drag and drop solution (e.g Apple Notes/Evernote).

2. Search

There's no point in setting up this system without being able to use it! Find a solution that quickly lets you search for information, in the Bullet Journal methodology, they make you setup a key which is a fantastic practice to index information.

3. Ease of maintenance

Work journalling is a practice in which the benefits compound over time, think of a system that feels frictionless to maintain. You don't want to keep switching systems, nor do you want a system that's bloated and painful to spin up and write in.

All this being said, you can always just use a pen and paper!

We've seen how much a work journal can benefit your Software Engineering career, but the key message here is just to get started. Don't spend a lot of time overthinking and engineering your system. At the end of the day, you want to spend more time using your system and leveraging the benefits, than organising and maintaining it.