Zettelkasten – Knowledge Management for Software Engineers

Knowledge Management for Software Engineers

Avatar von Eric

… or: How I learned to stop worrying and love the Zettelkasten.

Everyone has been there. An error message pops up, and recognition begins to dawn. I have seen this error message before, you think. But where?

You google it. The Stackoverflow links for this topic are all purple. You have been down this rabbit hole before. You remember. It was something weird … involving a specific version of … something. You recall solving this error message to get another error message to solve to get yet another. You remember solving the problem eventually. You also remember it took you more than a day, but you have no clue where to find the solution.

Our brains are flawed

Or rather, they aren’t. Our brains are really good at remembering the things that are actually important. Which means the things that are immediately important to us. Sure, software development is several layers of indirection removed from a hunter-and-gatherer struggle, but that doesn’t mean we care more about some aspects of our job than others.

Essential principles of Object-Oriented Design? Something that will help us write beautiful code any day of the week? Sure. Wake me up at 2 AM and ask me about SOLID. I’ll probably be up anyway – young father and all – and I enjoy chatting about tech. Ask me about the finer details of the version of a library some person who is no longer working at my client’s company decided to monkey patch and then hardwire into every area of their monolith, and I will be counting the minutes until I can banish it from my mind.

Luckily, I take notes.

Notetaking is hard / takes so much time / requires more self-discipline than I have. Or does it?

I might be a little bit obsessive. The thing is, I am motivated by streaks and doing small positive things every day without missing a day. My wife reminded me yesterday that I was typing my daily page of words while she was lying next to me in labor, so there might be some truth to that. I believe, though, that you don’t need to be. I will give you a system that will provide you with all the benefits for minimal effort. First, I have to clear up some myths.

„I have a graveyard of abandoned notetaking systems! I don’t have the self-discipline for these sorts of things!“

Truth time: We all have a pile of abandoned notetaking systems. I have a bunch of beautiful paper notebooks that I will not write into in the foreseeable future. I used to feel guilty about that. I used to feel like I was failing. 

But I wasn’t. And I don’t feel that way anymore. It’s okay.

You are not supposed to serve your organizational system. The system needs to serve you. Also, you won’t know what your needs are until you try things out. And your needs and life situation will change.

I used to take notes on my computer until I worked in a company where I was no longer the only developer. Then I (eventually) started bullet-journaling because people feel listened to when you are taking paper notes during your conversation. If you are hacking away on your laptop, they wonder if you are playing Minecraft. Then the pandemic hit, and my bullet journal became a clunky item on my busy desk. Things change.

„Notetaking is hard and takes a lot of time!“

False. We have all taken notes in the past for various purposes. We started in school, built upon those habits and techniques when we got our job training in whatever shape or form, and now we do it in our daily lives. When we think of notetaking, we might see an image of detailed Cornell Style notes [link]. Every detail was grabbed, headlines, table of contents, a bibliography, a summary, all of it highlighted in three different colors. I never even found them all that useful.

The way our brain works is by building abstractions, by drawing a map out of synapses between neurons that tell us the way to the fridge and brings it to mind when we get hungry. I can find my way to the fridge with my eyes closed, but I have no idea how many kitchen tiles I need to walk over to get there – an unnecessary detail.

One hindrance on our way to good notes is the *One True Way*s inflicted upon us by our former teachers. The truth is that each of our brains has unique structures – as no two people are exact copies of each other – and therefore, the most efficient and effective note-taking system is unique to every person. Furthermore, we don’t need detailed notes on everything for the same reason we don’t need satellite images to guide us to the fridge. There’s too much information, and the interesting stuff is hard to filter out. Good notes, actually good notes, look a lot like those weird Medieval maps (Here Be Dragons). It’s not like your actual brain doesn’t already look like that.

A good note for your context might fit on a sticky note.

„I’m still too busy to take notes; we are on a deadline here.“

Just like refactoring, note-taking wants to be done on-the-go, when everything is fresh in your mind. And just like refactoring, it actually makes you faster. What I tend to do is have a file open I call a Work Log. It’s a simple markdown file. I write down my current problem, I write down any solution I might try, quote all the error messages I get along the way and all the commands I run. Finally, I write down the final solution in a detailed and clear manner. Why does this save time?

Context switches cost less

Just like your computer writes the contents of its RAM to your hard drive, you too can survive everyday context switches more gracefully if you do a quick brain dump first.

Your insurance policy against recurring bugs

If finding the answer to something was painful, chances are, finding the answer will be painful again unless you write it down.

The first step on the road to automation

A three-step process, really. First, you do something and take notes. The next time you encounter something, you will learn if your notes were good enough to help you and improve them if not. The third time … well, you can basically just translate your note into a script. All of the knowledge is likely already there.

Your pairing partner will wait for you

Not really a way to save time, but this used to be a big one for me. As the driver, I wanted to implement the ideas of my navigator as quickly as possible! However, my pairing partners were used to waiting for tests to run, for Docker to start up, and for gems to install (shoutout to all Ruby fans out there!). Making a quick note about what we just learned about that one class didn’t bother them as much as I feared it would. 

Pro tip: Actually, let them see the notes. Not only will this act as a progress bar, but they can give you feedback if you understood everything correctly.

It saves money!

It’s the same argument for why we need tests and on-the-fly refactoring. It is the only argument required in a professional context. Most of the time, management is eager to have software developers produce some form of documentation. This way, you can actually oblige them.

„My notes are an unorganized mess. I can never find anything!“ – Choosing/Building the right system.

So congratulations. You have a collection of sticky notes or a paper notebook full of arcane details, or a git repo full of flow-of-consciousness markdown files; how in the world are you going to turn this into a usable system that will help you retrieve information on time? How do you organize without constantly reorganizing? Well, you read the title of the article.

Have you heard the good news about our lord and savior, the Zettelkasten?

Way back in the 1960s, there lived a researcher named Niklas Luhmann. Niklas Luhmann was a sociologist, but before he became a sociologist, he was an organizational researcher. He created a system to store his notes, written on scraps of paper (‚Zettel‘ in German), and ways to link them and reference them that probably – at the time – only made sense to him. 

At the time of his death in 1998, his Zettelkasten (‚box filled with scraps of paper‘) had more than ninety thousand Zettel, all of them with unique identifiers, all of them containing valuable knowledge. His system made him one of the most prolific researchers of his time, with many books and countless papers. He used to joke that writing them was easy; the hard part was taking care of his Zettelkasten.

The good news is, today, we have computers. Having a computer makes maintaining a Zettelkasten much easier.

So, how does this work?

  1. You keep taking notes in whatever way you feel comfortable with.
  2. Whenever you find the time, you break them down until every note contains one distinct thought you don’t want to break down any further.
  3. You give these notes a title that will be their filename.
  4. You link these notes to other relevant notes.

Quick example

So I’m watching a YouTube video that says something interesting I want to write it down. Experience mainly being the ability to remember your pain – ever want to quote a great talk you have watched, and you scour your browsing history and still can’t find it? 

Because I have. 

I first make a note for the video itself, saving the link.

filename: YT 10 things you didn't know about Kubernetes - number 4 will SHOCK YOU.md


Maybe I even write down the channel.

filename: YT 10 things you didn't know about Kubernetes - number 4 will SHOCK YOU.md

[[YTC Romantic Moments for Software Developers]]

This is basic markdown syntax. The note I creatively prefixed with YT for YouTube now links to a YTC – YouTube Channel – note called YTC Romantic Moments for Software Developers.md. My note-taking app doesn’t care that the file doesn’t exist yet. It can track theoretical notes as well.

Why is it useful to link it this way? I have tools to explore a graph of my related notes. If, at some point, I encounter another brilliant video from this channel, I can also link it and see if the points it makes connecting to the previous video in any way. Or if they build bridges to previous research in other areas.

filename: Kubernetes helps with Mindfulness.md
[[Kubernetes]] can be used as a technique for [[Meditation]] that helps with [[Mindfulness]], especially when hosting [[NodeJS]] applications.
This is similar to how [[Arduinos help you be more zen]].
[[Mini-Project Idea]]
[[YT 10 things you didn't know about Kubernetes - number 4 will SHOCK YOU]]

So we write down one of the video’s points, linking back to its source. Maybe I want to quote the thought, perhaps my notetaking arts will prove lacking a couple of months down the road, and I will want to watch the video again to figure out what I was talking about. The note links to various other notes as well. Some of them are topics like Kubernetes; another is a different thought altogether that is sort of related to this one. 

Then there is a tag. When I get one of those mythical slots of free time, I can look at all the notes linking to Mini-Project Ideas and get lots of suggestions.

But… why?

The power comes in connecting ideas. Often when creating content – like blog posts, hello! – you chain one idea to the next and the next. Zettelkasten will help you retrieve ideas that you had years ago. It will also contain all the relevant quotes, properly cited, if you put in the effort to do that.

Don’t impose a hierarchy. In Zettelkasten, every note is as important as any other note.

This sounds like so much work

It isn’t. It’s mostly cutting and pasting and filing stuff that is already there. All the notes go into your Zettelkasten, your beautiful compost heap of ideas. And it’s fun! Just putting those notes in there creates new ideas for me that create more notes, and so on. I get into a nice flow. And it doesn’t need to be done every day. Your Zettelkasten will always be there when you are ready, slumbering inside the git repo you hopefully backed it up to.

Picking the right tool

I know several people who like to use Obsidian for this system or similar ones. It makes everything a bit more comfy and generates a shiny graph you can explore. Of course, nothing keeps you from using a personal wiki, a folder full of HTML files, or something similar. I am currently working on a proper workflow using vim, for example. In the end, it has to feel comfortable for you.

Did it work?

So far, yes. The strength of Zettelkasten is holding on to those transient ideas, those passing thoughts, where we make connections between existing concepts that we can’t act upon. At its most basic level, it helps fulfill our use case of not getting blocked by problems we have already solved. We can find knowledge more efficiently. Everything is written clearly and concisely (ideally, if you take good care of your Zettel). 

Luhmann described using his Zettelkasten as having a conversation with a friend. Much more so than the second brain some apps try to sell you, there was an exchange, a flow, maybe even a sense of connection. 

I hope you give it a try. And tell me about it in a couple of months.

Avatar von Eric


Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Für das Handling unseres Newsletters nutzen wir den Dienst HubSpot. Mehr Informationen, insbesondere auch zu Deinem Widerrufsrecht, kannst Du jederzeit unserer Datenschutzerklärung entnehmen.