Notetaking for developers and techies

INTRODUCTION

I have lost count of how many times I have tried to find a note taking app well suited for technical notetaking. The closest I have ever gotten, is the Microsoft OneNote application. It has its strengths for sure, but it's not optimal for dealing with code snippets and the likes.

The stone of Obsius

Through a stroke of dumb luck, I stumbled upon an application called Obsidian. It is an application that lets you organize and work with notes. Notes are written in Markdown, a lightweight markup language that makes it very easy to style your text. Obsidian applies these changes as you write, so it is very close to Wysiwyg.

THE FIRST STEP

When you first start the application, it asks you to create a vault. A vault is simply a starting point for collecting your notes.

• We create the vault and open it.

On the left, we have icons for creating new notes and folders. The notes themselves are shown on the right hand side.

The first note

Typically I would start off with some sort of folder hierarchy to make it easier to track notes. So in this traditional mindset, we will do just that:

• We create a hierarchy of folders
• Within the Python folder, we create a new note: Variables

Markup within the note is rendered on-the-fly, making the note nice to read. However; so far, it looks sort of un-impressive. There are plenty of Markdown editors out there. What makes this one so special?

IMPROVING APPEARANCES

Obsidian, is pretty generous about letting us use CSS to style its presentation, making it straight-forward to add some colors to headers:

Writing notes are very fast, as your hands rarely leave the keyboard. It really fits the mindset of a developer.

LINKING NOTES

Good looks are only skin-deep though. The issue with note taking applications, is the ability to navigate notes after they have been created. Luckily, Obsidian makes this very easy.

• We create a new note named Functions

This particular note consists of:

• An observation made about functions
• A basic example code on how to define a function
• A list of use-cases

The list of use-cases contain bi-directional links to other notes. Obsidian makes it super-easy to create these.

When you encompass any text in double brackets, it automatically creates a bi-directional link.

With a link selected, you can simply press Ctrl + Enter, and Obsidian will create and open the linked note. In this way you can easily create a collection of linked notes.

• We create the linked notes and fill in code for each note

Writing up a series of notes in this way, is fast and effortless. The Obsidian interface makes it easy to navigate between them.

KEEPING TRACK OF NOTES

While Obsidian has proven capable in terms of producing new notes, the real litmus test comes next. A note-taking application is only as good as its ability to retrieve individual notes. After all, what good are splendid notes, if you cannot find them.

In our setup so far, we must pay particular attention to our folder hierarchy. We need to :

• store notes in the correct folders.
• avoid duplicate folders.
• handle cross-overs

etc.

The bigger the pile of notes, the more difficult all of this is to manage.

You may also have noticed, that while Obsidian automatically created linked notes, it simply put them all in the root folder.

This is not a huge problem, as we can simply drag them into the proper folders. The links will still work just fine.

However, there may be better approaches to managing notes, than using a rigid folder hierarchy. Let us explore that next.

A MINDFUL DATABASE

Obsidian comes with a plugin, that allows us to treat our notes as if they were items in a database. Basically, the whole vault becomes one large database of notes.

Defining keys

The first thing we need to do, is to define some handles, or keys if you will, onto our data. We need a way to categorize our data.

In our case, let's define two properties:

• level : basic, intermediate and advanced
• type : code and description

We then need to apply these properties to individual notes.

For example; for the Variables note, we add code as seen here to the top of the document.

There is a third property here named tags. It was added to provide a level of customization for each note.

We add similar code, for each of the remaining notes:

With the keys in place, we can use them in queries using the DataView plugin.

RETRIEVING NOTES

First, let us try to retrieve the Variables note. We create an empty note and fill in a code-block as follows:

This will return any note with the tag variables defined within. When obsidian renders this, you get the following result:

It resulted in a list containing a single item: a link to the note variables. You can hover the mouse over the link to get a preview, or you can click on it to open the note itself.

MAKING A MASTER NOTE

We can set up a master note where we define queries to relevant parts of our notes

I have defined two queries

• Notes: lists all notes designated description
• Code: lists all notes designated code

Should we add another note, it will automatically pop up here, given that we have assigned the proper key values at the top of the note.

LISTING CODE SNIPPETS

It would be immensely useful, if we could also extract tagged code snippets through queries. Sadly, that functionality is still in the works.

However, if we can live with one-line snippets, there is a simple work-around.

• We create a new note called One liners , containing a table of code snippets:

Each line of code starts with ?:: This defines an inline field, that is recognized by the DataView query. ( Note that we can name a field whatever we want. It could be data::, code:: , elephant:: etc. I simply used the letter ? to make the field identifier name take less space ).

Now that we have a field identifier, we can build a query to retrieve the associated code:

The output :

This approach is limited to one-liners, but depending on the language and environment you are working with, that may be all you need to make code snippets throughout your notes available in one fell swoop. Awesome, right?

DIAGRAMS

Finally, it would be nice if we could easily add diagrams to our code. There is a fantastic tool called PlantUML. It allows the user to create diagrams such as:

• class diagrams
• use-case diagrams
• state diagrams

and more.

PlantUML takes text that describe the diagram, and convert it into an image. As luck would have it, Obsidian supports PlantUML through a plugin.

Below is a code block, with PlantUML code that describes a class diagram for a hotel operation:

Obsidian automatically renders this into the diagram seen below:

FINAL WORDS

While I have only played around with Obsidian for a few days, I am absolutely sold on its features. It addresses most of my concerns with note taking apps, yet I have barely scratched the surface of what it can do. I am certainly looking forward to learn more about it.

Also, it's free, so you might as well give it a try.

RESOURCES

• https://obsidian.md/download
• https://plantuml.com/
• https://github.com/blacksmithgu/obsidian-dataview

( Header illustration background image: Gerd [email protected])

Bj?rn IF Westerheim
System and support engineer