Building a knowledge base as a software developer

When I started to work at my new job this year I also started to reflect the way I am taking notes and writing down things.

In the companies I worked nearly every developer had Notepad++ installed and a lot of tabs where they wrote down cheatsheets, things they learned, log messages they try want to investigate and a lot more.

But is this the correct way? Trying to find something which happened months earlier is not so good with unsaved Notepad++ tabs. I’m more of an analog guy when it comes to notes: In nearly every meeting I am taking a lot of notes, scribbling and drawing diagrams of application architecture and designs in a sketchpad.

But this is also not a good a way if I want to find something. Even a Table of Content isn’t better than a CTRL+F search in notes.

So as the structured man I am, I started to thing about a better way of taking notes.

I think everyone needs to find their own way to do this. This is how I am doing it and thing it is the correct way for me.

Define the goals

The first thing I wanted was to define the goals I wanted to reach with the enhanced way.

Mainly this was:

• Don’t forget what I did on day x
• Find things easier than on my paper-based solution
• Have a way to write down a structured cheatsheet
• A way to scribble ideas, take notes of numbers - fast!
• The data/tool should be easy to use.

Finding a tool

The goals are pretty easy and there are a lot of tools out there, which promise to help you building a idea tree and so on. You can take notes on Microsoft OneNote, find a self-hosted, blog-like solution or use some extensions for existing tools. Every of them has it’s own advantages and drawbacks. A lot of research time may be needed to find the correct one.

Found it! Foam

A co-worker of me recommended Foam. A knowledge-management tool which enables you to do what you want with it. Running as a VSCode extension it is easy and fast to use, as it is in the environment I am mostly using. So when I take a note, I just need to hit a Shortcut and I am in my own Foam where I can take notes fast.

How Foam helps to reach my goals

How does Foam help me to reach the goals from above? Let’s see.

Don’t forget what I did on day x

That’s an easy task for Foam. Just pressing ALT+d creates a new note for the day.

Find things easier than on my paper-based solution

The VSCode search helps with that.

Have a way to write down a structured cheatsheet

Cheatsheets do have their own directory (see in the bottom of this section).

A way to scribble ideas, take notes of numbers - fast!

As I am mostly working in a ticket-based environment, I am creating a new file for every ticket where I try my best to write down ideas/notes on the solution in a structured way. Quick notes and thoughts sometimes also will land on paper.

The data/tool should be easy to use.

Foam has no UI and works as an extension. So it is up to you how you use it or what you do with it. But basically it is working with simple markdown files. So it is hard to find something more simple.

Here’s the directory structure how I am using it:

foam
|- daily - Daily notes. One file per day.
|- tickets - Notes on tickets I'm working on. One per ticket.
|- cheatsheets - Structured Cheatsheets for CLI tools like kubectl.
|- assets - Quick scripts, recurring commands, recurring SQL scripts.

With this way I can find every time things I worked on in the past really quick. When I remember something I just hit the search and in a few minutes I am smarter again.

Conclusion

Foam seems to be extensible in the way it is used. So even if I want to reach another goal, then I can try to make it work as I want! And another thing is: It just are simple markdown files which are generated in my repository. So even if I change my Editor/IDE one day or Foam will not be maintained anymore (hopefully not!) I can keep the data or use another tool. The data can also be pushed into a git repository or stored in another environment. And as they are just text files, you could also think of using a static site generator to get a more beautiful view on it. I’m still using paper notebooks for some quick notes and thoughts. But the main action and most important things which have to live for a long time are living since 3 months in a foam repository!