Find My Team

Using Github as a Knowledge Base

Image of engineering blog author: Kyle RiesKyle Ries

The Search for a Knowledge Base

Google reports 109,000,000 results for the search query "Knowledge Base". 65,300,000 are returned for "Knowledge Base Software". As a software developer, that ratio strikes me as about right - developers love re-inventing the wheel and I enjoy tongue in cheek intros for blog posts. ;-)

So, as the TeamSnap engineering team continues to grow from a humble base of a handful of developers and LOC's under our belts to a more mature organization, it was time for us to make a decision about how we wanted to try and capture our internal knowledge in a way that was easily accessible and digestible (knowledge consumption) while still being reasonably easy to contribute to and search (knowledge documentation).

What We Wanted in a KB

As a remote team working varying hours and from strange and exciting locations around the country, we also wanted to make sure it was something that we would all be notified of as new entries were added.

With that basic set of requirements in mind, we considered a few options:

  1. Stackoverflow Q&A style site. Let's be honest, as engineers, we love SO. The interface, format, and Google-indexability of the site have saved many developers many many hours of headbanging about the strange things our computers do. We like SO so much that we really wanted that kind of experience for our own KB. Specifically, we looked at a few Wordpress and Slack plugins that purported to offer this capability.

  2. Dedicated Slack channel. We've come to love Slack. Each of us spends a great deal of time in Slack and, thus far, that is where most of the knowledge sharing occurs anyway.

  3. Dedicated solution (i.e. some CMS or another). We recognize that somewhere, someone has probably landed on the "Slack for Knowledge" and offers a great solution for the same problems everyone else is already having. Alas, we didn't want a paid solution. And, to be honest, our current engineer onboarding already includes many many various account/service provisioning steps that we didn't want to add another tool to the crowded toolbox.

  4. Build our own! Well, yeah - we build stuff, so we could do this. But, we should be building features that make a team manager's life easier - this didn't fit that bill.

What We Ended Up With

What did we ultimately land on? The oh-so-wonderfully-familiar-and-universally-loved....GitHub! As it happens, GitHub meets all of our requirements in the following ways:

  1. Writing up "issues" in the form of questions is a perfect way to start a conversation and provides the same SO feel we like.
  2. No additional account provisoning, onboarding, or training required. At least in the engineering team, GitHub knowledge is table stakes.
  3. Slack integration into a dedicated KB channel. Somebody write a new question? It'll show up in the Slack channel. Someone post an answer? It'll show up in Slack. No need to check your email for a GitHub notification.
  4. Question result in a pull request in the primary app README? Great! Reference the KB issue and close it when the change goes in.
  5. Tagging - we haven't really used this yet, but we can foresee this becoming helpful as our usage of TeamSnap and the KB grows.
  6. Markdown and image support - gives us all the options we need to get the content in there.
  7. No additional cost with our GitHub license!
  8. Easy to search from within GitHub or the dedicated Slack channel

What We Think So Far

For something with as much bike-shed potential as an engineering knowledge base, our decision to use GitHub as the center piece has worked out great for us so far. We've had 24 questions entered so far. Most have answers, many have closed w/ a change in a codebase, and so far it seems everyone is ok with the general format and toolset.

Time will tell if it scales well as more content is added, but given the KB is an internal support tool, we're proud to have landed on a solution that leverages existing tools and communication channels and is something that we setup in a matter of minutes. As an experiment, the KB repo is a great example of living by the TeamSnap Engineering Manifesto of delivering practical solutions in a timely manner.