How to Create Useful and Easy-to-Manage Help Documentation

A customer-centric approach to product, marketing and support is the key to building a great company.

As anyone who’s ever built a SaaS business can attest, it’s easier said than done. We always aim to help customers find their way and this, ultimately, served as the foundation for our decision to build our own help documentation.

Here’s a perfect example of how that approach manifests itself in a busy, growing company.

Last week, we launched new a help documentation site, help.getvero.com, to make it easy for customers to get started, use our API and answer technical questions about Vero. The new help docs are faster, more robust and just plain more helpful than our previous docs.

To power the new setup, we are using Github Pages, Jekyll, Algolia as well as our own Grunt deployment to host our CSS on the AWS CloudFront CDN. The infrastructure is better, the design is cleaner and the content is more useful. The end result is a focused site that meets the needs of our customers. Additionally, anyone can suggest changes, whether they be internal Vero team members (both engineers and non-engineers), customers or otherwise.

This post explores the reasons we chose to build our own help docs, the challenges we ran into, and how we stay focused on a customer-centric solution. Everything is open-source, so anyone can use this setup as a viable alternative to the various hosted SaaS help doc options.

As mentioned above, we have published our new help documentation as a public repository on Github that anyone can fork and edit to create their own help documentation (you can also create pull requests for updates to our own help articles).

Why we rebuilt our help documentation

We previously hosted our help articles on WordPress. Using a custom post type, docs were hosted on the same installation as our marketing website. WordPress was easy for our entire team, including the less-technical among us, to use and all us of pitched in.

Ultimately, this created some real challenges.

Using custom post types buried our help documentation inside WordPress, making it hard to find and update old articles. Our engineers weren’t invested in the infrastructure, making it too easy to put off updating the docs when we launched new features. Worse yet, we’d never spent the time to draft a style guide, so help articles were inconsistent and repetitive.

The decision to build, not buy

When we committed to fixing our help doc problem, the team evaluated a number of off-the-shelf solutions, including HelpJuice, Help Scout’s Docs, Zendesk’s Knowledge Base and a few other great products.

We use Help Scout for our email support (absolutely love it) and have previously used HelpJuice. Each is a great solution, but we couldn’t find a product that met our four key needs, which directly support our customers’ needs:

1. We wanted search to be super-fast. Slow search is almost as bad as no search. We know from testing that it’s how most customers find the help they need.
2. We wanted to be able to feature our status page updates, hosted on StatusPage.io as part of our design. Uptime is a feature and we want customers to know when we run into challenges that affect them.
3. We wanted to build a foundation that will allow for future customization. Support videos are the next thing to add but who knows that the future of support holds. We want to be ready to adapt quickly.
4. We wanted to be able to manage our own categories and navigation. We already know where customers run into trouble so crafting sensible navigation can guide them to quick answers.

When none of the aforementioned tools met these requirements in the way we really wanted, we began discussing the idea of building out our platform. The idea seemed crazy at first. After all, why reinvent the wheel? It would mean managing a CMS, worrying about deploys, setting up local environments, and worst of all, potentially wasting a lot of time.

We all baulked at a homegrown solution but did some research to confirm our suspicions. What we found, however, was that using Jekyll, Algolia’s Search for Jekyll Plugin, GitHub Desktop and GitHub Pages, we could actually run custom help articles with no deployment scripts, blazing fast search and a completely custom user interface.

Find a solution that works for engineers and non-techies.

Everyone on the team contributes to support, so everyone should be able to create and edit articles. Github’s Desktop tool makes it easy to update and deploy help articles, but it’s a new world for our less-technical team members. This is a real concern as getting developers engaged but losing the rest of the team wouldn’t solve our problem.

Interestingly, less-technical team members embraced the solution. It’s a good excuse to learn a bit of code and it brought different areas of the company together. We set a hard deadline to complete our docs and everyone contributed to the launch. There’s nothing like a due date to kick off a new process.

The key to this has been managing this process in three ways.

1. Using GitHub Desktop. It’s a lightweight tool that makes it easy for anyone to contribute code to a repository. Thanks to the magic of GitHub Pages, every deploy and push (or sync) to the master branch of our help repository means the code is automatically deployed. This is a huge win because it makes it easy for anyone on our team to get a local copy of the help articles on their computer, so they can edit them with their favourite Markdown editor. That means we can use the best tools for the each job – rather than the less-than-ideal online text editor offered by WordPress, team members can use their own editors. Rather than using WordPress’ limited functionality, we can build our own with Jekyll. Win-win.

1. Teaching our less-technical members about Markdown and simple tools like Sublime Text. Both applications let you open a folder of Markdown files for editing. These tools are built for editing Markdown, making them a gateway into the world of coding. We’ve found that our less-technical team members have really embraced them.

1. Writing a comprehensive README that explains, in detail, how to setup and manage the help docs repository locally. It’s help docs for our help docs.

To illustrate what we mean, we have found that all team members have been sticking to the following process:

1. We use GitHub Desktop to synchronise the latest version of the repository and help articles.
2. We add or edit help article files in Sublime or Write using Markdown.
3. We synchronise changes, wait for the deploy and do a final check that all looks good on the live site.

Maintain a consistent style. Everywhere.

To ensure our docs look great in the future, we added a section to the README file that detailed the guidelines for creating or editing help articles. These included:

every time we made some significant style changes,

• when to bold text;
• when to use italics;
• when to use code snippets;
• and how to handle screenshots.

We host our CSS centrally on an AWS CloudFront server. This is managed on a second repository (vero-styles) that we’ll make public in the near future. We’ve written some simple Grunt scripts that make it easy to run CSS changes locally, deploy them to staging and also to deploy and invalidate them on our production CloudFront node. By having our styles on Cloudfront, we minimise the load time no matter where you are in the world by serving the assets from the closest server to your location. Another win for everyone.

The other benefit of separating the repositories is that no individual team member needs to touch or manage the CSS. And thanks to a well-documented style guide, it’s still easy to ensure that the help articles, written in Markdown, will look great when it’s deployed to production.

To make it easy to review and manage images and links, we have centralised links.yml and screenshots.yml files. When we need to change the images or update the links, we only need to do so in one place.

Our style guide outlines how to crop screenshots, where to put the image asset files and how to insert the file using our screenshots.yml file and Markdown.

These rules ensure we can maintain a body of help docs that is reliable, sensible and helpful.

Address categories and ‘Common Issues’.

The home page for our new help documentation is centred around categories, and a ‘Common Issues’ section, where we highlight the most-asked questions.

In Jekyll, we created a custom collection to host our help articles so that we could define the sub-directory structure being used.

To do this, we had to define our own category management. We simply added three pieces of meta-data: common_issues, getting_started and categories. Each post can have a single category and, if present, the boolean value of true denotes that an article should also appear in the Common Issues and the soon-to-be-released Getting started headers on our help documentation.

This structure is easy for everyone on our team to understand and, thanks to Jekyll’s instant compiling, makes it easy to add or remove categories by simply no longer using a category in any help article.

Plugins and third-party tools

In pulling our help articles together, we’ve made great use of Algolia’s Jekyll Plugin. We wanted to write about how we handled this but it was so easy, there isn’t much to write.

Basically, you install the plugin, index your help articles and then go. We added some extra styles to highlight terms that the customer has searched. Algolia makes this super easy by highlighting the search facets – so even that was too easy!

We have also used StatusPage.io‘s awesome Javascript embed library to show customers the current status of Vero and also to highlight any open issues.

It’s easy to get carried away with features and plugins. Anytime we thought of new add-on to the help docs, we simply measured it against our guiding support principle, “does this help guide our customers?”

• In the case of well-indexed, fast search, the answer is definitely “yes.”
• In the case of a plugin to direct customers to our status page in the instance of issues, the answer is definitely “yes.”
• In the case of share buttons and comments, the answer is “no.”

By measuring everything against a single control, we eliminated a number of unnecessary features, spent less time on design and development, and created the most helpful help docs we possibly could.

Quality help articles are a huge advantage.

Vero is a technical product and a very flexible customer communication platform. Many of our customers have between five and 30 people logging into Vero – engineers, designers, marketers, product managers, support team members – and there is no way that all of those team members want to send emails to our support team when they have a question.

Great help articles guide new trial customers through the app. They help current customers learn new features. They help new team members get familiar with the software.

It’s important to consider an approach that works for your team and your customers. Customer support goes a long way in this business, so don’t skimp on it.