As our company has grown, we have faced an increasing need to create documentation about who we are, what we do, and how we achieve results. This lead me to look for a wiki or knowledge base system that would provide an easy to use, reliable place for us to store and share information for our small team.
Our needs are simple, and my must-have feature list was short:
- We like Markdown as a format for editing and sharing text
- We need the ability to do some simple organization and categorization, but nothing that crazy
- The content of the wiki needs to be quickly searchable
- It has to integrate into Slack!
It is crucial that the information stored in the wiki be available at our fingertips. The goal of having a wiki is to help our team build, document and stick with defined processes and standards, to record all the important technical details in a place they can be quickly referenced, and to put this information to work for us. For that to happen, Slack integration is perhaps the most important feature for a tool like this to be successful in our organization.
I did some research. There are a lot of wiki tools available, most of which were far too feature-rich for our needs. But I couldn’t find one that had all 4 key features I needed — particularly the combination of Markdown and Slack integration.
So, I built one.
Built for Slack
The primary way we use and interact with our wiki is through Slack. Search queries are submitted using a custom slash command, and content updates are shared via a dedicated #wiki channel. We even use Slack for user authentication — if you can access our Slack, you can access our wiki.
Now, if anyone has a question or needs to refer to our documentation, they can do so without leaving the conversation.
It looks like this:
Markdown + YAML
Based on some positive experiences we’ve had recently using the Jekyll static site generator, and pulling inspiration from the existing wiki tool Wikitten, I decided to build in a mixture of Markdown for content and YAML for metadata. (If you don’t know what YAML is, don’t worry — it’s just a simple format for storing information in a text file.)
In addition to the text content of the wiki page, users can add additional metadata such as tags, folders, and other information that is useful for search and navigation, but doesn’t necessarily need to be displayed on the page.
With the help of Angular and the fantastic Ace code editor, I created a realtime editing and preview screen for creating and managing wiki pages.
It looks like this:
Data-driven Navigation
Instead of creating a folder system or some sort of category management tool, we allow the content of the wiki itself to define the navigation. As folders are defined in the YAML front matter of the wiki pages, they appear automatically in the navigation. Documents can be added to multiple folders, or none at all. After we moved everything into the new tool, we ended needing just 9 folders.
It looks like this:
No Database
Until we built the wiki, we’d been using a Github repo of Markdown files to store our documents. Why change?
Our wiki software reads and writes Markdown files from the filesystem. With 100+ pages on our wiki, we can still do near instantaneous full text search. Plus, changes to the content can continue to be tracked using Git and backed up automatically to Github. And there’s no database server to worry about. And if we ever want to migrate to another system, we’ve got all of our data in simple, human readable text files.
Text files rule!
What’s Next?
We think this simple, Slack-based approach to organizational knowledge capture and management makes a lot of sense. It works like magic for us, so it might work for other people too!
If you’d like to use a similar system for your team, sign up for Howdy, a powerful workplace bot for Slack that will help your team capture and use the information they create and share.
