Building a static, developer-friendly, open-source knowledge base
In our work with government and enterprise IT, we’ve seen how user support can go terribly wrong. Enterprise software is often so complicated and unintuitive that it requires a hefty binder bearing the words “User Manual.”
After experimenting with a few options, from in-app tooltips to comprehensive phone support, we decided that an online knowledge base would be our best way forward. None of the existing out-of-the-box solutions fit our needs exactly, so we built our own from scratch. Here’s how we did it.
When we began, we knew that we wanted to write articles in Markdown and serve them as static HTML pages for efficiency and simplicity. However, we also wanted our static site generator to be intelligent enough to handle, for example, a table of contents that would update automatically whenever we added a new article. After trying out several static site generators, we decided on wintersmith, a “flexible, minimalistic, multi-platform static site generator built on top of node.js” that suited our needs perfectly.
The main challenge with a static-site approach is that it lacks some of the dynamic features users expect from a knowledge base, like full-text search. We were able to circumvent this limitation by using a node-based indexer that runs on a single Heroku dyno. It takes a query, finds the matching pages, highlights the matched words from the query, and returns this information as structured JSON. We use this app as the backend for our search page, which simply sends over an AJAX request and displays the results as HTML. Curious how we keep the search index in sync with our deployed site? Scroll down to the Deployment section below :)
The next step was to integrate our knowledge base with Screendoor, our flagship application. We wanted to display a list of relevant articles in Screendoor’s help menu that would change depending on the user’s context. For this, we needed a way to associate articles with specific views within the app.
We added an
app_pages field to each article’s metadata that contained a list of Screendoor page keys. For example, the article that describes how to add collaborators includes
projectwizard-collaborators, a unique identifier for Screendoor’s collaborators page, in its
Then, to find the relevant list of articles for each Screendoor page, we added another endpoint to our node-based search app. This endpoint takes a page key and returns a list of all the knowledge base articles that reference that page key in their
app_pages field. From Screendoor, all we needed to do was query this endpoint and display the results in our help menu:
We’ve been experimenting with matching the deployment process for our static sites to the one that we use for our dynamic applications. Here’s what we ended up with:
- When the
masterbranch is updated, CircleCI automatically runs our test suite (currently just a link-checker) and alerts us if anything goes wrong.
- Once we’re ready to go live, we merge
production, which runs the tests on Circle again (hey, why not?) and also kicks off a
- The Grunt task builds the static site, pushes it to the
gh-pagesbranch (to be served by GitHub Pages), and also pushes the
productionbranch to Heroku so that our search index stays in-sync.
The final product is served as static HTML and written in Markdown. This means that there’s no dynamic code to execute on each request, so our knowledge base is stable and as fast as can be. Our deployment system also makes adding a new article (or updating current ones) dead-easy: add a Markdown file to the
articles directory, and merge into the
production branch. That’s it!
Build your own!
When we were conducting research on how to implement our knowledge base, we couldn’t find any packages that fit our needs and allowed us the flexibility we wanted. If you’re looking for a knowledge base solution for your own app or business, we hope you’ll consider using ours as a starting point. Except for the articles, everything is released as open-source under the MIT license, so you’re free to do with it as you wish. Take a look at the code: https://github.com/dobtco/wintersmith-knowledge-base.
Aviv Nitsan is a developer at The Department of Better Technology.