An amazing note-taking system with Markdown and Git, Part 1

The evolution of one developer's note-taking habits…

I currently use an amazingly simple and effective note-taking system comprised of the following:

• Markdown files
• Git
• A Shell Script

I want to explain how this works in case it helps anyone else roll their own notes, but first I'd like to talk a little more about the many other ways I took notes in the past and their pros and cons, and why I have landed on my current system instead. I think this will shed a lot of light on the strengths of Markdown files + Git.

Paper Notebooks

Once upon a time, I took notes in paper notebooks. There was a problem I kept coming up against. Whenever some piece of vital information had been written down, but slipped my mind due to a lapse of time, it was hard to determine exactly:

a) when I wrote that down
b) where to find it

This was exacerbated by the fact that notebooks would get filled up and I might be working in a totally different notebook at the time I wanted to refer back.

There were other disadvantages to paper notebooks. One habit I've practiced for awhile is keeping a to do list. On paper, to do lists don't seem like they are worth the effort because you either carry over tasks from prior days to new days, or you try and keep one list going over several days. For the carry-over method, manually copying text by hand from one page to another feels like a waste of time (because it is). For the one list method, you inevitably run out of space on that page as new tasks are added, and so you have to do this weird thing where you reserve several empty pages

So due to these and other issues paper notebooks got the boot from me many, many years ago. I started my tech career about 17 years ago, actually, and abandoned paper notebooks a long time back.

Email

Outlook has built-in notes, to-do lists, and a calendar. At one point the way I took notes was by emailing myself, then either flagging the emails that needed action or converting them to notes, to-do items, or calendar events.

I bounced off this system pretty fast because it felt so cluttered. Trying to ram notes and to-do lists on top of the incoming onslaught of new email just made this experience feel chaotic.

OneNote

Everyone was using EverNote or OneNote at one point in time and I picked up the habit as well. One huge advantage of these pieces of software is their ability to hold attachments and links to the external world.

OneNote is so great, I thought at first. Notes were "in the cloud" in OneDrive and therefore accessible anywhere. I could use a phone, tablet, or my laptop to take notes. I could have separate notebooks for personal and professional use, but use the same system.

Then I ran up against a variety of issues around intellectual property and security. My company actually forbade us to take notes in the public cloud. I could still use OneNote if I pointed at a work-managed instance of OneDrive. But this made that promise of "notes anywhere" not a reality anymore, because I could only use devices that had a VPN into my work network.

Still, it was an easy enough issue to work around.

Then a new problem reared its head. My note-taking habits evolved. I was no longer taking notes only at meetings or for task lists. I am a software engineer. I started to keep monospaced text in my notes. I had little snippets of Java, BASH, JS, XML, JSON, and more that I wanted to note down. Quite frequently, I wanted these formatted a certain way (spaces not tabs!), and that certain way was entirely clunky to achieve inside OneNote.

Raw text files

At this point, I converted over to raw text files. I wrote a very simple bash script so that I could enter notes from within a Terminal for quick notes:

$ n 'Had a meeting with Cindy today'

My script would automatically take care of timestamping the note and saving it into a file named after today's date. If that file didn't exist yet, it would create it. If it did already exist, it would append it to the end of the file.

It was a pretty simple system and didn't need a lot of overhead to provide some huge advantages:

• Compact
• Easily searchable (using grep)
• Great support for code snippets since code snippets are text

There were some disadvantages, though:

• Cannot link to anything in the outside world (no clickable URLs)
• No images, audio, video, etc.

So this system worked great for me for about a year, but I found that I had a number of photos of whiteboard drawings or image files exported out of LucidChart or even file attachments such as test plans that I could only mention in passing in my text notes, rather than directly including them.

So, I evolved. Stay tuned for the next installment of this series and I will explain exactly how.