My favorite note-taking method

Posted on 2019-11-03.
On Hacker News, Reddit, and elsewhere, people often ask about favorite note-taking methods. In this post I share mine.

As long as can I remember I have been taking notes. Taking notes is a good way to free the mind of constantly having to remember everything. Especially when you're studying complex subjects where you encounter new terminology, concepts, and perhaps syntax.

Another great benefit of note-taking is that once you have finished studying a subject or testing out technology, you can mostly just rely on your notes for future references.

However, a very important part of note-taking is to keep your notes organized and structured. If you haven't got a good methodology your notes can quickly grow on you until you spend to much time doing it, and eventually you feel overwhelmed. Perhaps you end up having tons of notes lying around.

I have 3 main methods I use.

  1. I have always a pen and paper ready somewhere. When I have a thought, or get an idea, or suddenly remember something I want to investigate, I take a quick note. If the thought is worth saving, I write it down on my computer sometime later. Otherwise I get rid of the note as soon as I am done.
  2. Learn by repetition. This has nothing to do with taking notes, however it is still relevant because it makes it possible to completely forgo taking notes.
  3. Taking notes on my computer for long term storage.

I use learning by repetition whenever I need to memorize something that I use often or something that is very important. I might keep some notes in the beginning, or for later reviews, but the point of repetition is to avoid having notes in the first place. Learning by repetition doesn't really require any kind of schedule or anything, you just have to make sure you repeat the things you want to learn often enough.

When it comes to long term storage I have tried out different strategies and applications over the years, but in the past couple of years I have settled on a very efficient and simple method.

I have a single Git repository for all my notes. I write all my notes in Markdown because it makes it easy to structure the notes, and it makes it super easy to incorporate images, links, and other material during the note taking.

I use a Git bare repository to keep the notes in sync across multiple computes. I pull from and push to the repository. In Git (from version 1.7.0 and above) the repository has to be "bare" (no working files) in order to accept a push.

I have made a command alias so I can do an easy commit and push in one simple command which also uses rsync to copy the files to a webserver. On the webserver I have setup a NGINX redirect that redirects Markdown files to a simple PHP application that renders Markdown into HTML on the fly. Autoindex is enabled for that particular directory on the webserver. My notes are occasionally used by other family members and friends, and as such they have easy access.

I take notes using Neovim, and I mostly just read my notes in Neovim. When I need to look at my notes as HTML, perhaps because they incorporate images and lots of links, I either browse the webserver or use the markdown-viewer extension to Firefox from Keith L. Robertson.

The markdown-viewer is great because you can use your own CSS stylesheet and it is possible to render local files on your computer. It also knows how to generate a TOC.

On Linux you add the following XML to ~/.local/share/mime/packages/text-markdown.xml:

<?xml version="1.0"?>
<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
  <mime-type type="text/plain">
    <glob pattern="*.md"/>
    <glob pattern="*.mkd"/>
    <glob pattern="*.mkdn"/>
    <glob pattern="*.mdwn"/>
    <glob pattern="*.mdown"/>
    <glob pattern="*.markdown"/>
  </mime-type>
</mime-info>

Then run:

$ update-mime-database ~/.local/share/mime

This makes it possible to use the FILE:/// URI scheme. Just bookmark your local note directory.

I organize all the notes in a directory hierarchy according to subject. So it looks something like this:

...
├── revision
│   └── git
│       ├── add-new-empty-remote-and-push-to-it.md
│       ├── checkout-deleted-file.md
│       ├── checkout-older-revision-of-a-file-under-a-new-name.md
│       ├── cherry-pick-vs-merge.md
│       └── whatchanged.md
├── security
│   ├── a-bcrypt-hash.md
│   ├── acl-selinux-apparmor-grsecurity.md
│   ├── analyse-process.md
│   ├── best-algo.md
│   └── files
│       ├── password-rules-are-bullshit.pdf
│       └── your-password-is-too-damn-short.pdf
├── standards
│   └── standards.md
├── steam
│   └── steam.md
├── useful-links.md
└── video
    ├── avidemux-correct-usage.md
    ├── encoding.md
    ├── ffmpeg-conversion.md
    └── images
        ├── bar.png
        └── foo.png
...

This means that when I use the Markdown markup for images, they automatically gets incorporated in the rendering.

So if I click on the "ffmpeg-conversion.md" note, the image "foo.png" gets displayed using:

¡[foo](images/foo.png)

I use grep and find for searching and I have divided directories into subjects with subdirectories, which again sometimes contain other subdirectories (depending on the subject). This makes it easy and very fast to search even though I have many files.

When relevant, a directory might contain a files subdirectory, an images subdirectory, and a video subdirectory. Images are obviously for storing images. This might be a screenshot, a photo, or something else. Videos are very rare, but I occasionally store something which I find important. It might be a quick video I have shot myself, or it might be something from YouTube that is related to the subject. The files directory contains PDF's and other files that I have downloaded from somewhere. It can also be a webpage I have printed as PDF which I then link to from inside the Markdown document.

If I find some important information online that I need related to my note-taking, I don't trust the webpage to always exist on the Internet, I therefore always take a copy for offline usage. Sometimes I just download the page as a single HTML page, other times I print it as a PDF.

I work a lot with bare-metal and I occasionally test out a new technology or some cluster feature. When I setup a test lab I always take notes of everything. It is important for me to be able to reproduce the same results multiple times, and when something goes wrong I need to be able to follow-up on the issues and document bugs. Important commands, settings, responses from the system, everything gets documented. That way I can make sure I write good documentation, and that I have actually tested every single step before I publish anything.

When I study a new subject I often do the following:

  1. I first begin by collecting as much relevant information as possible. It might be physical books, online articles, documentation, tutorials, and video. During the initial stage I first try to grasp a single issue that I then make sure I understand very well. That way I can use that issue to determine when a book, an article, or a tutorial explains that particular subject well. If it doesn't it often doesn't explain any of the other concepts well either. This method works most of the time as an easy way of sorting, with the occasional exception.
  2. Once I have gathered all the relevant material I then dive into the depths of the subject. During this process I often do a second level of sorting. I am only interested in the most relevant information and the best sources.
  3. Then I begin taking temporary notes and do testing (if it is testable). Testing involves trying out different setups and approaches, it involves finding out when something stops working. If it is a new programming language, and if it is suitable, I often try to clone some application that I have made in another programming language. This makes it interesting because I am able to compare how I might solve the same problem. If I run tests over a period of more than one day, I add dates to my notes. That way I can come back and see the progress I was making.
  4. When I am done I do a clean-up in my notes. Notes that was written down during a bug-hunt or something less relevant I delete. Such notes where only relevant when I was in the middle of the process, they are less useful later. Notes that was written down during a problem solving session are very important, I might run into the same problem later and have forgotten how I initially solved it.

During my note-taking I write down everything I consider important as if I where to suffer a temporary memory loss. If I ever needed to go back to my notes, I don't want to depend on anything but the notes. If I depend on anything besides my notes, then the notes provides me with the relevant information about such things.

I also write down small notes to myself, within my notes:

REMEMBER: Always check the log for foo when you issue the bar command!

Or:

REMEMBER: You have already read the book Foo, the examples the author provides are useless. There is no need to go back to that book!

Yes, I have actually found myself studying the same subject twice, several years in-between, because I had forgotten that I had already looked into the issue. That's extremely annoying! :) What's the point of taking notes if you forget your notes? So, as a good habit and reminder, always search your notes for a subject unless you're absolutely sure you haven't dealt with the subject before :)

Finally I occasionally do a clean-up in my notes. There is no reason to keep outdated notes lying around. Notes on how to install Postfix on Debian Potato is hardly useful today. Unless of course you want to keep a history track of your notes, which I don't :)

Before I settled on the above method I used DokuWiki. DokuWiki is a fantastic Open Source wiki software that doesn't require a database, but instead uses flat text files. It has a clean and readable syntax, but can also be expanded with modules to support Markdown and other formats. DokuWiki is very easy to maintain and backup, and it has a build-in revision system that works really great.

Whenever I am in a new project with multiple people, I always try to "push" DokuWiki as a note taking and documentation solution.

Anyway, this about sums it up :)

If you have any comments or corrections please feel free to email them to me.