Knowledge as Code: Making Creating Knowledge Easy

In Part I I introduced you to Knowledge as Code (and KCS). In Part II I'll talk about some of the practical hurdles every adopter of KCS will run into and how that shaped our Knowledge as Code journey.

The largest hurdle in implementing KCS is a practical one, adoption. How do you get your folks already killing themselves to react to your case volume to create content? We know objections are quickly squashed the first time an Engineer's weekend is salvaged after finding a problem has already been solved and a knowledge article created, but therein lies the crux of adoption, creation.

There are very few tools to enable this practically and almost no tools everyone can agree on (as anyone who has implemented or is currently maintaining a KCS strategy will attest to). We decided that making it easy to contribute was priority #1 for our team. The goal; enable our team to use whatever tool they wanted!

Looking at similar working models we realized Developers already solved this problem. Using their IDE of choice they were writing code in the tool that best suited them. The answer to our question was both self-evident and already within our wheel house. Enter Source Control Management and the birth of Knowledge as Code.

By moving our knowledge creation and content into Github we solved a number of issues. From consistent formatting (markdown), version control, and for the KCS zealots gates for whatever rules you deign necessary (technical validation, formatting, etc...) supplied through the PR process . Being stored in an SCM our knowledge is now free to be used for any number of purposes. One example is Professional Services and Solution Architects who can now checkout our knowledge for when they're onsite and have a flaky internet connection. They can also create new knowledge disconnected to be merged later.

git is is great for our developers and folks in the field, but what about our Customer Success team? Github provides a bare bones editor which for the purpose of creating knowledge is as easy to use as any. We settled on using markdown which may require some learning, but if you follow the principle of KISS in your formatting it's fairly straightforward and requires very little from a "coding" perspective.

Here we are with all this knowledge and everything to do with it! So how do we practically make this available to customers? Github may satisfy some users, but is decidedly not the presentation model we preferred. Also, what about the gates mentioned earlier should we do those all in Github or is there perhaps another best practice we could leverage? Not to mention stakeholders! Now that we have this who else can use it and for what purposes?

In Part III we'll talk about how we're leveraging Jenkins and Workflow to answer some of the questions above!

James Brown
Director of Global Customer Engagement
CloudBees