Live documentation with Obsidian

A problem any developer knows: a software project that lacks documentation. The code might be overcomplicated, and of course the least documented parts of it are changing most often, and thus are more problematic or complex.

Here’s an approach I’ve tried out, and it seems really promising. Live documenting the project with Obsidian notes, a wonderful note-taking app that is based on Markdown, supports cross-note links and can be synchronised over a Git repository.

We will be solving several problems with this approach.

First is that code comments are usually not enough, and also they do not tend to age well. How many of those decade-old TODOs have you encountered in legacy codebases? How many comments in a codebase make things harder to understand, because the adjacent code was changed, but the comment itself was never updated?

The second one is keeping track of your architecture decisions while keeping track of when and why those were taken.

And the third one is (probably) dailies. If you want to keep track of who’s working on what each single day, this approach will give you some more clarity, of course at the added cost of some self-discipline.

Why Obsidian? #

Obsidian has several powerful features that you’ll have to know about before proceeding.

First, it’s all markdown with some sugar sprinkled on top. The main thing is that you can link any notes in your vault (or a note repository) by simply using the double square bracket notation like this: [[Ideas/Split InvoiceController into separate action classes]]. Cmd+clicking on such a link either creates a new note for you if it didn’t exist before, or otherwise it takes you to an existing note.

Second, the daily templates. You can set one up in the app settings:

And the third feature that’s worth noting in our current context is the graph view which gives you a nice understanding of what, when and where you’ve touched in your codebase.

The approach #

So, there are two sides to this idea. The first one is a daily chore. All you have to do as a developer is to keep track of your day-to-day duties and write those down. I’ve created a daily note template that consists of several sections:

• Tasks
• Issues
• Ideas

Tasks is a list of things I have been doing during the day. If I get a new task during the day, I add it as a to-do item right in the daily note, like this:

  - [ ] [[Tasks/Implement a new endpoint for accepting payment callbacks]]

I would usually copy the task definition itself into the note that I’m linking to. And then, while working on the changes, I would write down stuff that’s directly linked to the task into the task note. This would usually be things like further breaking down the task or adding notes on some specifics. Other things go to a different place.

For example, during investigating the system I figure out that the request handling is not optimal. While working on the PaymentCallbackController I notice that usually people tend to decode JSON requests by calling parent class methods. I decide that this is a potential problem. Thus, my next steps would be:

• Add a link from the task item to the code annotation note. An annotation note’s path should follow your code as closely as possible.
• Link up other files related to the code I’ve touched, while still adhering to paths in the actual codebase.
• Optionally add a separate note that describes the architectural problem I’ve discovered somewhere under Issues/.

So, I end up with several notes. Here’s a quick sketch on how this might look.

Tasks/Implement a new endpoint for accepting payment callbacks.md:

Touched [[Classes/Controllers/PaymentCallbackController]] which extends [[Classes/Controllers/BaseController]]

Classes/Controllers/PaymentCallback:

[[Issues/Inheritance used instead of composition]]: extending [[Classes/Controllers/BaseController]] makes things hard to maintain; suggest using composition instead, switch to a middleware to process things such as request decoding.

I might also create [[Issues/Inheritance used instead of composition]] note straight away just so that I could see it in the graph view. Also it’s sometimes worth linking the newly created issue to your daily note.

If you stick with this approach for long enough, even when working with legacy codebases, you will get a nice overview of what happened when, and what are the most critical problems of your codebase. Moreover, if your whole team will track their daily activities in this format (perhaps, having a subfolder for each member’s daily notes), your knowledge base will be more complete, and the collaboration effort will be quite easy to grasp. Remember that the storage backend is just Git!

The only con of Obsidian: syncing to Android via Git is complex to set up. Syncing with iOS via Git appears close to impossible. But the suggested approach is anyways intended for non-mobile usage.