How I take work notes as a developer

I take extensive notes about the world around me for various reasons. I earlier wrote about how notes are tool for thinking, writing, learning and productivity which was a high-level overview.

Last summer, as I was working with new people in a new team, I ended up having multiple great discussions about taking work notes as a developer and how I do it and why. Those inspired me to post in Obsidian’s forum about the topic and I’ve been thinking about it even more since.

Five types of notes

My notes system has evolved to include five types of notes. It’s not a prescribed system but rather described one. What I mean by this is that it’s not a framework I decided to follow and then fit stuff into those boxes but rather I started with just notes and over noticed that they fall into these categories. I’ve been inspired by reading many others’ explanations of their systems.

Daily notes

The first “layer” of my notes system is my daily notes. In my personal notes, these are more journaling style but in work notes there’s bit less reflection.

I create a new note for each day and keep track of what I’ve done that day on a top level, using bullet points. I jot down what meetings I had, what projects/features/tickets I worked on and other similar practical daily activities.

Daily notes help me gain a better understanding of where my time goes, when I’ve done specific things and during times when I struggle to see progress, I can look back into my notes and see if that’s justified feeling or not.

At the end of each note, I try to come up with one win for the day as a practice of gratitude. Sometimes it’s easy and clear to come with them, sometimes it’s really hard.

At the beginning of the week, I also create a week note and I go through the entire week’s calendar and mark down scheduled meetings, events, deadlines and other things I want to remember to see. It’s my todo list for the week and at the start of each day, I check what I have that day and the rest of the week so I can adjust my daily plans.

Meeting notes

For each meeting, I create a new note. This is not used for meeting minutes as those are usually recorded into somewhere shared but it’s a canvas for me to keep track of things I feel important.

Crucially, I create these notes when the meeting is created or scheduled. I write down the important discussion points that led to that meeting being scheduled and between then and the meeting itself, I have a place to collect thoughts in a way that I can easily find and recap right before the meeting.

I track the date, who were in that meeting and then have two sections: Agenda and Notes.

In Agenda section, I write down my preparations for the meeting: questions I need to remember to ask, topics I want to bring into discussion and potentially collect links to other relevant documents.

In Notes section, I collect things I’ve promised to do, action points that land on under my responsibility and other notes that I want to keep in my own notes in addition to the shared meeting minutes.

These notes are then helpful in keeping track of my action points that I have to fulfil. I can use them to check what I’ve discussed with someone or regarding some project the last few times instead of trying to remember all that.

Running notes

Running notes are the bread and butter of my notes in this system. The goal of them is to document the work that I do including the mistakes, explorations and detours that led nowhere. For development stuff, they often include snippets of code or shell scripts, lots of links to documentation, voicing my assumptions and a step-by-step process of getting to the finish line.

Sam Bleckley calls these Lab Notebooks and says:

One of the hardest things about software engineering is that, while it’s often possible to understand the code you committed, it’s usually impossible to see all the things you tried first, that didn’t work.

They are very raw and kind of append-only in a way that if I notice something was wrong, I don’t delete it. I want to keep a history of where I went wrong as that can also help finetune the processes or improve documentation once I’m done. I do sometimes polish them up a bit once I’m done (meaning adding headings, improving flow, adding links to documentation) but I don’t change the content.

I find it very valuable when I start a new task, to start by understanding what I’m going to do, see if there are any gaps in my knowledge. I can then seek discussions with colleagues and users to gain a better understanding before I then start my work.

Whenever I follow a documentation, for example setting up developer environment, I document the commands I run as provided in the documentation and document if there are some problems. If those problems occur, I can then bring the solutions back to the documentation once I’m done.

Writing notes while working allows me to focus on the work and continue on that path without losing track of issues or workarounds that need to be documented later. It’s relatively straight-forward for me then at the end to go through the note and extract the information into other systems.

Charles Féval writes about how his work journals help him regain focus after a disruption:

And boy oh boy did that help! I just re-read what I was doing, and boom! I was back in.

These running notes also help a lot if at some point a discussion starts about some of the decisions. I can always refer back to my notes to see what I’ve considered, what discussions happened around them and why I made the decisions I did.

If there’s a ticket that I’m working on, I name the running note with the ticket ID and in the body I link to the ticket, the pull request (once it’s done) and other relevant documentation or discussions so there’s one place where I can find them.

Tanner Christensen keeps work journals and describes his approach as:

Anything from setting and evaluating common goals for yourself or capturing a message about a challenging interaction with a co-worker are great uses of a work journal. It's a private and safe place for you to catch daily or weekly notes about the things going on in your work, the good and the bad. There's no right or wrong way to keep a work journal, but a few things I have learned through experience can make yours even more valuable as a guide for building case studies.

Topical notes

Topical notes are self-contained and well written notes about individual topics. As a software developer, these are often either research/learnings on a technical topic (like how to structure/architect REST API endpoints) or recipe-style snippets (how to cherry-pick commits in git) where I document what I’ve learned while working.

Over the years of writing code, I’ve noticed same questions come up over and over again, sometimes frequent enough that I start to remember them but also often rarely enough that I don’t. In the latter case, it’s really handy to be able to find the notes, written by me for me, that help me figure solutions to problems. I also extend these notes whenever I learn new things.

They are also fantastic because they make sharing knowledge easier. I often publish these notes in my blog and in /snacks. Other people keep TIL repositories (like this one by Lacey Henschel or this one by Simon Willison) where they share these kinds of notes and I love them.

Notes are nice because I can return to them but I also benefit from them when I’m writing them because writing helps me clarify my thoughts and spot the gaps in my knowledge. I also usually then remember them better because I’ve written them down and processed them an extra time.

A good example of a recipe-style note from my system is this one I shared in my /snacks collection.

Sometimes these notes are link collections. I have one for accessibility where I collect great articles from the web when I run into them and categorize them by topics so if I end up in a situation where I need to work on forms, I can find all of my notes and links regarding accessible forms in one place.

Brag document

A part of work is that someone somewhere eventually evaluates whether the work we do is good enough. Whether it’s a client or a supervisor or a potential future employer, it’s a built in part of this work life system.

Many companies do reviews every 6 or 12 months. If you’ve ever been to one, I’m confident you’ve at least once had to think really hard what you had been doing 6 months ago or 12 months ago. It’s a long time and a lot happens.

A brag doc is a note where we keep track of our successes and good work we’ve done.

You are the only person with complete insight into everything you do. You are the person who can most accurately and effectively hype yourself.

Marie Chatfield Rivas has this great quote about how we don’t want to leave this to the hands of the manager or the client because they don’t have the full insights. Keep track of the impactful work you’ve done so you can refer it to later when reviews are happening.

Julia Evans has also written about them with great insights:

This blog post isn’t just about being promoted or getting raises though. The ideas here have actually been more useful to me to help me reflect on themes in my work, what’s important to me, what I’m learning, and what I’d like to be doing differently. But they’ve definitely helped with promotions!

I personally have two: one for my current work that’s usually focused on the review cycle and another in my personal notes where I collect all the positive feedback I get from people, whether given privately or in public like social media.

I regularly read the personal one through with hopes that it reminds me that I am achieving and doing things that have a real positive impact to other people’s lives.