In every software development project, there are things to remember, like what time we get to the office, or who’s in charge of planning the next birthday party. Some tasks are remembered by a tool like Jira or Pivotal Tracker, like the priority of tasks and what makes up each Epic. The repository remembers other things, like what each function does, and how to deploy the app. But there’s another category of knowledge that often has an ambiguous or clunky home: decisions and reasons.
This critical information is the kind of thing that, in a high-performing team, is written down somewhere. But the tools for managing knowledge on a small team are often kind of terrible. Wikis are durable, but their UI is usually clunky enough that I think twice before adding anything. There’s a moment where I have to decide if my thought really warrants a new page or an update.
Like a source control branching strategy, if a team knowledge management system is too ambiguous or onerous, the team won’t use it at all. If your team doesn’t have a knowledge management system you like (or if you don’t have one at all), and you’re frustrated by the other offerings, give Obsidian a try and see if it doesn’t improve your team’s memory.
Where should you put your memories?
Obsidian is just a nice UI for a folder full of text files. There’s no weird proprietary format, no database that you have to manage, no security model you need to understand. If you can manage a folder, you can manage a vault. If your team can manage a shared folder, then they can manage a shared vault.
I bet your team is really good at managing a shared directory of small files that people make regular changes to. If you’re working on a software project, then you’re already halfway there. Make your Obsidian vault a subdirectory in your source code repository. You probably already have SCM access for everybody on the team. You can modify files easily using Obsidian, and then they can be versioned using your SCM of choice (it’s probably Git).
If you’d rather not go the full SCM route, consider adding your Obsidian Vault to your team’s Google Drive, One Drive, Dropbox, or iCloud drive. Since it’s just a folder full of tiny text files, nearly any cloud sync engine will do. If you want to get nerdy, you can even set up a cloud-free distributed sync system like Sync Thing for maximum nerd points.
Here’s what to write down.
The rules of a shared team knowledge base are simple: Write. Everything. Down.
If it’s not in the vault, then it didn’t happen. You know those meeting notes you’ve been scribbling in a Google Doc? Put them in the vault! The decision that you made in Slack? Put it in the vault! With an Obsidian vault, you can capture the text of any decision and make it instantly searchable by your entire team. Right-click any Slack message to copy the full text. If you’d rather not duplicate the text entirely, from that same menu, you can copy a deep link to any Slack message.
And, here’s how to write it down.
An Obsidian vault tends to work best when it’s filled with a lot of small notes that are richly linked together. Each kind of thing gets a tag. You might wind up with tags like #meeting, #decision, #person, #risk, #idea, #feature, and #bug.
When you take meeting notes, instead of just typing out the names of everyone who attended, add their names in [[]] square brackets. The first time you meet with somebody, you’ll spend about 30 milliseconds more typing those brackets, but every time thereafter, you’ll be able to autocomplete their name. When you learn something about a person on your team, say their favorite snack, or the thing on the project that they really like to do, make a note for them! Now that knowledge can benefit the whole team.
When you think of a risk or find a bug, stick it in the team’s Obsidian vault. Link to it from the #meeting where it came up. Now you have a record of exactly when it was discovered and who a developer could talk to for more information.
Use plugins to make that knowledge even more useful.
- DataView makes it easy for developers to write little queries that find notes. Think: “All the meetings from last week” or “A list of all the bugs that we’ve found, but not yet fixed, sorted by recency.”
- Templater makes it easy for everybody to produce notes quickly with all the right info.
- Paste URL into Selection is how every text field should work. When you have a URL in your clipboard and you want to turn some text into a link using that URL, just select the text and paste. Now the text is a link. Simple.
- Copy Block Link makes it trivially easy to copy a link to a block of text within any Obsidian note so that you can paste it as a Transclusion within another note. Say you’re tracking down a bug and want to include a paragraph description of the issue from some meeting notes. You could copy the text and paste it. Or you can copy a block link and paste that into your bug report. Less duplication. More DRY.
Exalt all of the voices on your team.
Having a team vault that’s easy to edit lets you benefit from the best of each person on your team. Information packrats like me can throw as much information into the system as we can think of. Gardening types who like to prune information can edit and refine it. New folks can use their fresh perspective to ask new questions and fill out gaps in the team’s knowledge. Seasoned hands can use the vault to guide their thinking. Bring all of these voices into harmony with a shared team space that leverages everyone’s strengths to build a durable record of every decision your team has ever made. You can do this with any tools, but Obsidian makes it really, really nice. And fast.