Lessons Learned Building a Git-Based Knowledge Base for my SaaS product

July 24, 2015

TL;DR: I built a Knowledge Base for my cash-flow forecasting SaaS app WiseCash, using Jekyll and GitHub. I’m sharing a Jekyll template you can start from, as well as what I learned building this.

In this post you’ll find:

A free Jekyll template for you to get started!

Inspired by KissMetrics who are using a public git repository for their own Knowledge Base, I’ve chosen to make my Knowledge Base template freely available.

You can use this as a starting point for your own product. Just make sure to tweak the look so it doesn’t look too similar (fonts, css, colors) and to avoid reusing written content! A credit is appreciated but not required. Enjoy and share!

Get the Knowledge Base Jekyll template

Motivations for creating a Knowledge Base?

I had several motivations to build this:

  • Improving communication with existing customers when activating a new feature that needs a bit of understanding (such as the brand new Profit Center Forecasting).
  • Building reference material that I can link to when emailing / tweeting anyone (“here is how you can do this”), customer or not, during trial or lifecycle emails.
  • Give a bit more details to people who stumble on the landing page and would like more information about how WiseCash works, before considering starting a trial.
  • To some extent, building some keyword-rich content for SEO.

As of today, I already referred to my KB quite a bit, so I’m fairly happy with the outcome already!

Careful: a Knowledge Base takes time to build!

What takes most time is not the technical aspects I’m discussing below. It is, as often, the production of written content, pictures, structure and linking. The complete setup and content (17 pages) took me 58¾h, as reported by Freckle:

kb-freckle-report.png class="img-responsive" [resize:75%]

That said I could have started with a bit less content and still get a use out of it!

Why not outsourcing my KB to a SaaS app?

There are some products around (such as UserVoice, Readme.io) that I could have used.

That said our revenue is not huge and I also wanted to have a great control to customize things as I want (such as: adding a bit of javascript for a third-party service, colors, SEO etc).

So for this round I decided to keep things home-baked. In hindsight I’m fairly happy with my decision, for my own personal context.

Why GitHub?

I already use GitHub for all my work. Using it with a separate repository allows me to invite other people to contribute easily, without having to share the whole application codebase. This could include technical writers, anyone who would spot a typo etc.

If you spot an error, you can click on the “Suggest edits” link on each page, and create a Pull-Request right from the page, thanks to this Jekyll include.

Also, Git in general allows branching, scripting, versioning, all things I appreciate dearly as a developer, and which are super useful for a documentation effort!

Note of warning: if you use the same technique, make sure to properly review pull-requests you may have, since this is served from the same domaine as your app. Do not let uncontrolled javascript comes in, for security reasons!

How is it hosted and deployed?

I initially attempted to use GitHub pages for deployment, which is super easy to setup, but:

I felt that in 2015, supporting SSL properly was important, even for a Knowledge Base.

I also considered deploying to S3 (where plugins is not an issue, since you build your KB locally), but then I investigated the SEO status too and realized that according to Moz (Feb 2015), it’s still better to use a subfolder rather than a subdomain for SEO reasons:

I can't tell you how many times we've seen and we've actually tested ourselves by first putting content on a subdomain and then moving it back over to the main domain with Moz.

For this reason I decided to simply publish the KB content in a subfolder. Basecamp does the same, presumably with some sort of load-balancing/reverse-proxy in front of it, which is still possible for me if traffic grows.

For deploying I’m just using a Rake task as part of my regular application deploy, but I can also deploy the documentation without having to deploy the application itself, to make sure to reduce interruption of service for my customers.

Get the Knowledge Base deploy script

Look-and-feel and layout inspiration.

Getting started from scratch can be intimidating. Quoting Justin Weiss:

This is very true when it comes to finding “good documentation”! So I remembered the nice docs I recently came across, including:

In the end I built my own layout, yet these docs helped me brainstorm what I liked.

How to embed images and animations?

The Knowledge Base is screenshot & animation rich, which is not surprising since WiseCash itself is a fairly visual application. For still images, I used Skitch, which allows to put those pink arrows that almost no-one can miss:

account-overview.png class="img-responsive" [resize:75%]

I noticed that reducing the scale to 75% avoids blending the image with the KB site too much, so I wrote a little Jekyll include for that.

I used ImageOptim to compress the images, especially since this is my main server which will serve them for now (not an issue at this point).

I also wanted to feature animations of the app. I initially thought about using Wistia. I already use Wistia as a paid customer most notably for the homepage animated loop. Yet I wanted to have something more lightweight and easy to refer to.

After a couple of attempts with various tools, I ended up using LICEcap, a free-tool to generate animated GIF. Their page is not looking great, but the tool works good enough:

Here is a concrete example:

set-bank-account-balance.gif class="img-responsive" style="width: 75%"

Not pixel-perfect, but not completely bad either, right?

Note that I do not scale the animations using jekyll-assets, because when I tried, it generated too much compression artifact (blurry animations). Instead I scale using CSS to avoid this.

Content organization.

In hindsight, if I started again I would maybe try Middleman, since it seems to be a better fit for sites like a knowledge-base. That said I have a decent level of control:

I use this to generate the table of contents.

Adding and reviewing a page is easy, which allows my (non-developer) wife and associate to contribute easily. Win!

Jekyll goodies.

To easily link between pages based on title alone (without having to refer to the url) and reduce chances of broken links, I wrote a Liquid plugin which allows me to write this:

[the link content, The Title Of The Page To Target]

The plugin turns this syntax into a proper link to the referenced page, based on the provided title.

I also have a little pagination system which is completely messy and way too complicated, but could be simplified with a bit of work.

SEO considerations.

I’m not doing anything too fancy at this point:

Also, I’m using the subfolder setup as recommended by Moz.

I will work more on that part at some point.

CSS trick: auto-numbering titles.

Basecamp uses a nice CSS trick to automatically number their guides steps using CSS counter-increment. I re-implemented something similar here, which allows me to declare this in the markdown:

## Do this

Do something.

## Do that

Do something.

And to get this automatically:

counter-increment.png class="img-responsive" [resize:75%]

No need to define the steps numbers anymore.

Markdown tricks.

The FAQ table of content is generated automatically using this syntax:

* Will be replaced with the ToC, excluding the "Contents" header

Linking to an item in the FAQ is highlighted using the CSS :target selector:

highlight.png class="img-responsive" [resize:75%]

Your turn!

I hope you learned some useful tricks here, and that my template will also be useful to you or people you know to reduce the friction of getting started. Thanks for reading!

Thibaut Barrère (WiseCash founder)



Thanks for sharing this article around!

Still managing your business cash-flow in a spreadsheet?
That must hurt, right?

WiseCash helps you rule your finances with an iron fist,
without having to labor a spreadsheet!

comments powered by Disqus