Updated Support Docs: A Better Way To Find The Resources You Need

Supporting Support

Maybe you’re new to SparkPost and you want a guide to get started. Or maybe you’re a long time pro and you want to test your production list with a sink server. For these things and everything in between you’ll find the answer in our support docs.

Sounds pretty standard for most companies, right? Unfortunately we’d gotten a lot of feedback from our users that our support website was difficult to use. From their perspective, the search didn’t always return the best results, the navigation could be confusing at times, the content styling was inconsistent, and the design hid information cues about the the page below the fold. We were using Desk.com behind the scenes to build out the site, which was a fine solution, but didn’t allow people outside of our support team, including our fine community members, to improve our documentation.

Our new setup allows our users to not only find what they need quickly, but allows them to submit changes or even add new articles if they’re so inclined.

What Changed?

The tl;dr is we moved the support docs into GitHub, open sourced it, shoved the articles into Algolia for awesome search, and wrote a pipeline right into our sparkpost.com WordPress website. Whew! We also redesigned the landing page to help call out resources for getting started, migrating from other providers, and getting help. Let’s roll up our sleeves and and dig into some of the changes that we made.

Into the weeds

Prison break: hacker style

The first step was to to get our articles out of Desk.com. They have an API, so with a little work we wrote a script to export the articles from desk and convert them from HTML to Markdown. This was relatively easy, albeit tedious -- since the Markdown converter had some trouble with the messy HTML there was a bit of manual cleanup.

Each category of articles was stored in a folder, which had an index.md file to store any metadata. Within each category folder was a media folder for any related images.

articles/
├── category_name/
│   ├── media/
│   │    └──my_article/
│   │       └──some_picture.png
│   ├── index.md
│   ├── my_article.md
│   └── another_article.md

WordPressing

Next up was pushing the articles into WordPress. To start, we first needed to set up a custom post type and taxonomy in WordPress for the support articles and categories. We used a library written by our very own Jason Rhodes to simplify the management of our custom post types. With a couple of custom templates, we were good to go on this front.

<?php
// Support Article CPT
new CustomObject('support_article', array(
  'singular_name' => 'Support Article',
  'plural_name' => 'Support Articles',
  'description' => 'Support Articles',
  'supports' => array('title', 'editor', 'author', 'excerpt', 'custom-fields', 'revisions'),
  'public' => true,
  'has_archive' => false,
  'show_ui' => false,
  'taxonomies' => array('support_category'),
  'rewrite' => array(
    'slug' => 'docs/%support_category%',
    'with_front' => false,
  ),
));

// Support Category CT
register_taxonomy('support_category', 'support_article', array(
  'labels' => $support_category_labels,
  'rewrite' => array(
    'slug' => 'docs',
    'with_front' => false,
    'hierarchical' => true,
  ),
));

With regard to search, we decided to use Algolia which has worked really well for us with our API documentation. They built a really great WordPress plugin that handles indexing, multiple environments, and the search that you see live. Needless to say, we’re big fans.

Laying the pipeline

This final piece was the most complicated. We needed to push any changes to the categories, articles, and media in a way that worked across our local, staging, and production environments.

To build out this we used:

• Bash + WP CLI, a super useful tool for interacting with WordPress from the command line.
• Some JS for converting the Markdown to HTML.
• Travis CI for automated build and deployment

We wrote a wrapper around the WP CLI to handle the environment variables that we stored in Travis. During each deploy we first updated the categories, followed by each article. The categories are fairly straight forward: find the changed index.md files, and update the corresponding categories in WordPress.

Handling the articles is where it gets interesting. There are a bunch of states to account for. You could replace and move an image in an article, move the article to a different category, or even delete the entire article and rerun the deploy. We took the safest route of rebuilding the entire world around the article on every update, including the metadata, images, and actual content.

Don’t let this fool you -- while it sounds relatively straightforward, each of the above steps could be a whole blog post on its own. Maybe I’ll dig into that someday, but for now, feel free to dig around the deployment scripts and reach out if you have any questions. And if you find a typo in our docs or want to write an article about using SparkPost with your favorite email client/tool/language, simply submit a PR on the docs repo and we’ll take a look!

This post was originally posted on the SparkPost blog.