Logo for The Department of Better Technology.

Rewiring Government

The Department of Better Technology helps governments deliver great digital services to the people who depend on them.

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.”

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.

Wintersmith

Wintersmith is simple and transparent, yet easily customizable. It doesn’t do much beyond transforming a directory of Markdown files into HTML via a templating system, but it’s also hackable enough that we can add a working table of contents through some custom JavaScript, without having to worry about yet another framework or library. Even though Wintersmith advocates a somewhat hacky mix of markup and custom helpers in the same file, the result is concise enough that we’re OK with it.

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 :)

Screendoor Integration

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 app_pages field.

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:

help menu

Deployment

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:

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.

Want more articles like this? Subscribe to our newsletter.