Running notes are the bread and butter of my notes that I take as a software developer.
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 fine tune 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.