In this post you’ll find:
- A free Jekyll template for you to get started!
- Motivations for creating a Knowledge Base?
- Careful: a Knowledge Base takes time to build!
- Why not outsourcing my KB to a SaaS app?
- Why GitHub?
- How is it hosted and deployed?
- Look-and-feel and layout inspiration.
- How to embed images and animations?
- Content organization.
- Jekyll goodies.
- SEO considerations.
- CSS trick: auto-numbering titles.
- Markdown tricks.
- Your turn!
A free Jekyll template for you to get started!
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!
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:
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?
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.
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!
How is it hosted and deployed?
I initially attempted to use GitHub pages for deployment, which is super easy to setup, but:
- You are limited to these plugins, yet I wanted to use jekyll-assets + custom code.
- SSL on custom domains is not yet possible.
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.
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:
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:
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.
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:
- Top-level sections are defined in sections.yml.
- Each page belongs to a section and has an index in the section (see front-matter here).
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!
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.
I’m not doing anything too fancy at this point:
- H1 for the title of the page.
- Proper title tag.
- Meta description automatically generated or overridable if needed.
- Canonical page url (especially to avoid slash vs. no slash).
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.
And to get this automatically:
No need to define the steps numbers anymore.
Linking to an item in the FAQ is highlighted using the CSS :target selector:
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!
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!