As a engineer learning new languages, tools frameworks etc is just part and parcel of the job. Over time the spectrum of knowledge a full stack engineer has to learn has increased dramatically. Maintaining a cognitive memory across all the different CLI's, languages/frameworks etc in today's setting is no small feat.

Over time i've found that if you want something to stick you have to write it down, and if it doesn't stick (or un-sticks over time) you need some notes to look back at it. As my brain 🧠 ages these notes have become invaluable, and the need for quality notes over rushed pasted snippets has become more of a priority.

Due to this I decided to revisit and reassess how I learn, and in doing so I ended up discovering Obsidian which has been a game changer for me. This article is an engineers perspective of creating dev notes to aid in learning and recollection.

My old setup

Prior to Obsidian my note taking activities all occurred in OneNote, I had both my personal notes as well as learning notes around different technologies all in one place split by sections.

My programming category would contain a new section per technology

The notes themself's contained a mixture of,

• Images (mostly diagrams)
• Paragraphs
• Code snippets (sure you can use gists or a repo, but i want context with my code snippets and i want it to be searchable)
• Links to articles, tools, documentation links ect.
• Youtube links usually tutorials

However I realized that there are some serious shortcomings with OneNote, and these problems are replicated across its competitors too, like Notion or Evernote. Heres my list,

• Code pasted in is never pure code, they always add markup on top to render which means copying and pasting out adds characters or unwanted proprietary formatting
• Diagrams are always disconnected, hard to edit. They are usually pasted in images from other tools.
• I don't have any version tracking, history or backup.
• Pasting and editing is distracting with as styling gets pasted in from the source.
• There are no connections in my notes, linking is not possible.
• I dont truly own any of the content, i will forever be tied to whatever I write in.

The list can go on, but you get the idea...

How Obsidian makes it better

Obsidian is part of a next generation in IDE's designed specifically for research and note taking in their own words they describe it as,

A second brain, for you, forever. Obsidian is a powerful knowledge base that works on top of a local folder of plain text Markdown files.

Its the VS code of markdown... no quite literally. At its base it provides a really smooth cross platform writing experience with some key features,

• Markdown editing, you get all the benefits of being able to easily style without leaving your keyboard, as well as encorperating code snippets easily.
• Tagging and creating links (backlinks) across your markdown files
• Graph view (more on that later)
• Powerful built in search

And just like VS code its got a rich plugin ecosystem that's powered by opensource github projects that greatly extend its usability and allows you to mold the app to your liking.

You own what you write

Obsidian uses local markdown files that are stored on your own computers file system. There is no proprietary formatting, encoding etc, what you create is just standard markdown files (.md) and a bunch of folders.

Why is this important you might ask?

• It means the notes you painstakingly curate are not locked into a single echo-system, you can shift between them as long as whatever your shifting to supports markdown.
• You also get greater control over how you backup and manage change tracking.
• You have greater control over the privacy of what you write, in a world full of breaches a shift away from centralized cloud storage is refreshing. harshibar sums it up nicely with this video,

Works with git

Obsidian doesn't support git right out the box, it requires a community plugin called Obsidian Git. However after having installed the plugin you end up with the greatest change tracking/archiving tool at your disposal.

Whilst the extension is fairly simple in that its mainly for pushing changes to a selected branch. It offers enough functionality to be out of your way. Dealing with more advanced scenarios like merge conflicts might need to resort to the CLI.

Mermaid

As a visual thinker who thinks takes more information in from pictures than words the expression a picture speaks a thousand words really hits home. In the past I would always use free tools like draw.io to make diagrams then paste in the exported jpg's into my notes.

As a process I always found this really disconnected, and its even more jarring when you need to make edits and go through the whole export to jpeg flow all over again. I also find with these tools getting boxes to line up with connecting lines in a way that doesn't look a mess is incredibly fiddly and time consuming.

One later evolution of this was Plant UML which moves away from drawing diagrams to scripting, take this plantUML file as an example,

@startuml left to right direction actor Guest as g package Professional { actor Chef as c actor "Food Critic" as fc } package Restaurant { usecase "Eat Food" as UC1 usecase "Pay for Food" as UC2 usecase "Drink" as UC3 usecase "Review" as UC4 } fc --> UC4 g --> UC1 g --> UC2 g --> UC3 @enduml

Taken from the plantUML's usecase examples

The above script produces the following diagram, note that the formatting/spacing and styling is all governed by plantUML syntax... there is absolutely no drawing involved.

The benefit of this approach is you now have a change tracked diagram that can sit somewhere with your documentation (and as a bonus it formats everything for you). Aside from exporting the script as a .png making edits couldn't be easier.

Whilst PlantUML is great it still take you away from your markdown document as you need to separately create the diagram and later paste in a link to the exported image. A later evolution on this is Mermaid which is similar to PlantUML but works within markdown as a code block. Having diagrams integrated means you no longer need to export diagrams to jpeg when adding to a markdown file... their just there. Here is an example,

stateDiagram-v2 [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*]

Taken from Mermaids state diagram example

The script produces the following diagram, note that this screenshot was taken directly from Obsidian as it supports Mermaid out right out the box.

Creating a open graph of knowledge!

Obsidian has the ability of collating all the connections through back-linking and tagging your document to produce a networked graph. Take a look at my graph so far,

Here's another picture of it zoomed in, you can see all the connecting notes, as well all the connecting hash tags.

Admittedly whilst this looks really cool i haven't made much use out of this so far. It could be because I always target specific topics to learn and research into them rather than just free write so there's no real discovery of connections happening. In a team setting however the graph view could be really useful for content discovery especially when its cross cutting (like filtering on any article that's tagged with infrastructure).

Plugins

Obsidian has a wide list of plugins, I thought it would be useful for someone new to Obsidian to get a sense of how its functionality can be extended. Below are some choice selections I use personally,

Name	Description	Github Link
Advanced Tables	Adds better navigation and formatting for markdown tables	advanced-tables-obsidian
Syntax Highlight	Adds highlighting of code blocks within the editor view	Syntax Highlight
Markdown prettifier	Fixes and formats your markdown file	Markdown prettifier
Mind Map	Creates mind map view of your document	Mind Map
Natural Language Dates	Allows you to easily add dates into your markdown file	Natural Language Dates
Note Refactor	Allows you to extract a piece of markdown into its own file	Note Refactor
Obsidian Git	Adds support for git, allows you to push changes to your repository	Obsidian Git
Outliner	Adds better list manipulation, also allows you to fold lists	Outliner
Paste URL into selection	Allows you to paste a link over text and auto format it	Paste URL into selection
Reading Time	More for the blog authors, gives you a reading time for your markdown file	Readming Time
Recent Files	Adds a panel showing recent opened files	Recent Files
Sliding Panes	More of a UI change, allows you to slide between files	Sliding Panes

Themes

Obsidian also supports a bunch of themes and looks utterly glorious, I use a theme called Atom.

Conclusion

Obsidian has really refreshed how I work to a modern standard. Hopefully this has given a good overview of the benefits from a engineers perspective.

The only caveat to Obsidian is the lack of mobile apps (its currently being worked on, check out there roadmap on Trello). But to be honest I haven't really felt the need for it as im always learning whilst on my computer.

Obsidian is free try use (and fully functional with its free tier), they also have some paid tiers and boltons, so do check it out!