Take Public Notes

Senior engineering series: 4

The Senior Engineer Series is a multipart blog post describing the best practices and lessons I employ as an experienced software engineer.

Taking notes at work is not a new piece of advice. However, my very normal take is that your notes should be public in your company. I am going to first explain why you should adopt the practice of taking notes and making them public. Then I'll share the mechanics of how I do it in my own work.

Why public notes

There is a solid argument to be made that writing is the greatest technology of all time. When you write a thought, you make it retrievable. Being able to recall one's thoughts on command is a super power.

Public notes enforces a level of rigor and accountability that is unattainable by any other method. If I know that even a single person might see something I write, I am going to put in one hundred times the effort than I would just writing for myself. When I jot a note in a notebook for myself, my quality bar is simply, "Is the scrawl legible enough for me to read in the future?" When I type for myself, it's hard for me to self police beyond, "I'm pretty user these two words will remind me of the full thought." They didn't.

A common question I get about public notes is what if I can't put what I'm doing in my public notes? This is actually a powerful heuristic baked into the act of public note taking. If you can't write a bullet point about what you are doing, should you be doing it? Your note taking practice comes with the assurance that you will always have this nudge to work on problems that matter.

When you keep public notes, you will start noticing a few benefits.

By keeping a long running public notes doc (more on the mechanics below), you are creating a database for yourself. Everything you need is one cmd+f away. Some people call this zettelkasten, others call it second brain, but they are loser nerds. You are a Senior Engineer.

One day, someone will read your notes and share a piece of information with you that will be very helpful. Without your notes, they would never have realized how useful their information might be for you.

Your notes will subsume the need for a brag doc. When it comes time for performance reviews, your task will be to edit, not to generate. All of the work is already recorded.

If you find yourself often wondering, "What did I even get done this week?" look no further than a well-maintained public record.

If you do this long enough, you will also begin to notice the patterns and seasons of your work.

The mechanics of public notes

I use Google Docs for my notes, but like the stack rank, the substrate is secondary to the functionality. Your medium should allow you to @ people (not notify, just refer to the same person consistently and ideally with some autocomplete functionality). Your notes has to have a URL. You must enjoy writing in your notes. If Google Docs does not check that last box for you, find something that does.

Each week I start with a blank template. My template starts with the first day of the week to which the notes belong.

# Date in your favorite format (I preffer MMMM DD, YYYY)

# TLDR
A one sentence summary of the week.

# Reflections
Ideas and thoughts that I've had during the week.

# Readings
A bulleted list of everything I read for work this week
example:
- Project Very Normal Engineering Plan, author, tweet length summary.

# Protips
Commands, shortcuts, links, and advice for future me. For example "If you need to find X, use this query."

# Conversations and meetings
A bulleted list  of all the meetings I have with attendees and a short  summary, and a link to meeting notes.

# Creative work
A bulleted list of everything I create during the week including pull requests, code reviews, design docs, documentation, etc.

At the start of the week this template is blank. As I work, I add to the it. As much as possible I seek to write notes as part of my work as opposed to in addition to my work. If my notes get too nested, it's a sign that the item may need it's own doc that I can link to. Sometimes I get behind on notes. This is okay. This template is always open in my browser. This template is also private. It is the staging environment for my public notes.

On Friday afternoon I open my public notes doc. I reread my notes from the week. This is like studying in college. I update my TLDR to summarize my week. I copy the notes from my template and paste them at the top of my public notes doc. Next, I send the new notes I've just copied as a message to a Google group of teammates and coworkers who have added themselves to this mailing list. It was an empty mailing list at first.

Subscribe to Very Normal and follow the Senior engineer series for more insights and strategies to thrive in your software engineering career.