Summary
Sharing knowledge in a team can be a challenging endeavour, especially when different people are comfortable with different tools for that task.
In one of my last workplaces the familiarity with tools was privileged for quite a long time, resulting in a dispersed knowledge base, composed of google sites, google drive documents, powerpoints, slack pinned messages and companywide emails.
That had to stop, I pushed for a reorganization of the data.
After several discussions we agreed to move to a markdown based unified knowledge base. Initially this was done at a department level using wiki.js, then we had a companywide unified knowledge base using Obsidian.md.
Goal
Knowledge sharing in a team is hard enough without the medium working against it. All the company’s shared knowledge should be accessible on a single platform, with complete transparency, entirely searchable, easily discoverable.
Entering content should be as frictionless as possible, with keyboard shortcuts for the savy and UI options for the beginners.
Images and other mediums should be supported in the tool of choice.
Syncing, linking and sharing should be also possible and of no issue.
Last but not least, the tool should not lock you in, by allowing the content to be portable.
Execution
More than the technical issues, here the biggest hurdle was the buy-in from the rest of the team. Initially there was a strong opposition to moving away from the comfort zone of the tools already used.
The only subset of the team I was able to convince from the start to shift to a unified knowledge platform was the rest of the programmers. Namely the tech department, across several projects, with the aim to share there our technical knowledge only.
Part of the agreement in my project was that we would keep linking every new document in the google site that was supposed to be the previous project knowledge hub.
After the initial push, we started using a wiki.js instance to manage our knowledge base, wiki.js is a markdown based wikipedia-like content management system. It was a nice improvement but still had some problems like requiring a lot of friction when creating a guide with several screenshots. Still, knowledge started to coalesce in one place from across several projects that were being developed in parallel in the company, coders were showing it around to other departments by sharing guides.
A few months down the line there was a new push to get a unified documentation, led by me and several others. That’s where the opportunity arose to push for the adoption of Obsidian.md, a tool that I had discovered one or two months earlier for my very own personal knowledge management ( see here ).
The end result was structured as a fully unified knowledge base held in obsidian, synced through perforce between company members and with some pages even published to a password protected site using obsidian’s publish service.
Obsidian resolved also the last issues: images could be copy-pasted rather than having to go trough an upload process. Quickly one of the programmers took the initiative to develop a plugin to sync Obsidian with a keyboard shortcut, resolving the last nuissances with syncing.
Retrospect
This was a learning experience for me, before this process started I had only experience with confluence as a tool for knowledge sharing in gamedev teams. I had also never encountered a team where the information was fragmented on so many different platforms.
The real difficulty was to get the process started and win over the inertia, pushing the team to acknowledge that we had a documentation problem and to agree on what we wanted from a solution to the issue.
Once that was done, finding a software that would make us happy was a matter of time.