In software development, deeply understanding complex entity relationship models often occupies a huge amount of brain space. Keeping track of these models, along with any business rules surrounding your primary objective, can feel like running through one of those mirror mazes — you think you see the light and then you’ve slammed headfirst into a wall. On my current project, we are migrating data from an older system to a newer one. Translating the information is not a one-to-one migration. One “Event” on the old system often becomes two “Events” plus a handful of side effects in the new system. Circular dependencies have tripped up our team more than once, and remembering how all the entities played into each other was important but difficult to remember. We decided to try adding Obsidian. It went far in creating a coherent visual model we could use for both reference and knowledge transfer.
Choosing Obsidian
As a markdown-based platform, Obsidian is incredibly standardized and easy to share among team members. This is a huge win, as it allows us to check in our documentation alongside the rest of our code. Outside of the standard markdown functionality, Obsidian’s visualization features filled in the gaps, especially for those of us who are more visual learners.
Documenting Relationships Made Easy
Using Obsidian, we documented each entity we were translating, creating separate files outlining the old and new structures. This approach helped us reference specific aspects directly and clarified how different concepts interrelate. The graph view feature became a game changer. We could effortlessly visualize how data transitioned from the old entity to translation implementation to the new entity.
Being able to summarize data flows alongside context for expected values helped us identify dependencies and transformations quickly. Below, you can see how we captured the flow of data from the old to the new entities with reference to the specific values we expected in the translation work. Both of these visual features helped facilitate accurate knowledge-sharing discussions among the team.
Collaboration Without the Hassle
One of the standout benefits of using Obsidian is how it streamlines collaboration. In a team setting, overlapping edits are bound to happen. A useful tip I picked up along the way is to use Git’s --ignore-all-space option when committing documentation changes. This little trick minimizes merge conflicts, especially when multiple teammates are editing the same markdown sections.
In my opinion, documentation is always some of the most dreaded work. While Obsidian doesn’t relieve all the effort (I’m looking at you, generative AI), it does make the outcome a lot more pleasant to parse. That goes a long way for offloading the brain power of recalling entity relationship models, and future contributors will thank you!