If you’re a web developer and want some insight into how you could use Obsidian to track what you work on, today is for you. I’m going to give you a tour of how I use Obsidian to track GitHub issues and document our site setup.
As this is a working Obsidian vault, I’m not sharing it for you to download. Some of the information in it is sensitive and shouldn’t be shared outside our development team.
Obsidian Plugins for Web Developers
First, since we post a lot of code in the vault we have the Copy button for the code blocks plugin. This makes it easier to copy full blocks of code from the vault without needing to highlight the code first.
Another plugin that is a must to help standardize how we format our notes is Templater. With this, we have defined templates when we need to track our Github issues somewhere outside of Github. I’ll talk more about issue tracking in a bit. I did a full look at Templater for Obsidian here.
The final plugin we use is Copy as HTML since our release notes must be formatted as HTML and they get written in Obsidian. With this plugin installed, I can copy the highlighted text out of Obsidian as HTML. If you want a full tour of it, check out my video on the plugin.
Syncing Obsidian via Git
To sync our vault and keep it private we use Github. I’ve done a full video on how to set up Obsidian Sync via GitHub. GitHub allows us to have a full change history for the files, and we can add new developers easily by inviting them to our organization. Plus, we don’t have to pay extra for the sync service.
How we use Obsidian to Track Development
Issue Tracking
Not every issue ends up in Obsidian, because some are quick fixes that don’t need any type of research or further notes. When an issue takes a few sessions of work to get done and involves research, which probably has dead ends, we store that information in Obsidian. Even with only a few dozen Github Issues documented this way, looking back to see why a decision was made is very helpful.
I know many developers say you should just look at the code, but writing why a specific approach was taken is so helpful for future developers. It’s far too easy to think you have a better solution, only to realize later that it’s a dead end. When deadends have been documented future you doesn’t have to run headfirst into that wall a second time.
A regular development journal can also help show that you were in fact working. Many of my recent issues have been headscratchers that took multiple days to sort through. These were days without commits to our code. While the company I work for just trusts me, having a development journal would head off any questions about what I was doing while I was trying stuff that didn’t work.
Tracking Release Notes in Obsidian
We do monthly release notes, though we push a number of times a week usually. While I could go back and write notes for each issue just before we put out the notes, that’s a recipe for me forgetting exactly what a ticket addressed. As soon as I finish an issue and deploy it I add it to our release notes.
Then every month I go through the notes and decide what to highlight before it goes off to the content editor that changes it to match the new tone we’re developing for our customer-facing communication.
We also follow a similar process for a quarterly accessibility blog post.
Writing Developer Documentation in Obsidian
Finally, documentation is stored in Obsidian. One of my biggest gripes about developers is how little they want to write documentation. Sure write some code, and maybe you’ll be able to read it later and know what it does, but maybe not. When I lead teams I make every developer write documentation in their code, and do at least a first pass on some type of documentation for their entire team.
Here is one terrible example from the current project I’m working on. While WordPress has a standard way to add Widgets to the interface, that’s not what was done with the code here. The previous developers wrote a library so we have to add a new widget by adding content to an array. Then our library looks at the array and adds the widgets specified.
Not only was this not documented in the code, but there was also no written documentation anywhere for how this works. When I needed to add a new widget at the end of 2022 I had spent far too long banging my head against the wall trying to get the final step of this whole process working. Then when I was unable to solve the problem I had to reach out to the old developer, who is still around to advise, to ask how to finish off the work.
Once everything was working I added documentation to the code, then wrote a How-To article in Obsidian to show any other developer how to add a widget with our library for widgets. It took me around 20 minutes to write the documentation, but if it had been written already I would have saved at least 3 hours of my time as I tried to figure out what custom way things worked with the system.
A good development team writes documentation, not just code.
If you’re using Obsidian to manage anything with your code practices I’d love to hear about how you do it.
Getting Started with Obsidian
If you want to learn your way around Obsidian so that you can build a great note system then this course is for you. I’ll cover basic folder structure when to use tags or links, and the plugins I think everyone needs to make their Obsidian experience excellent. Plus much more. If you want all my courses, become a member.
$99 USD (30-day guarantee)