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.
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 corporate 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.
│ ├── media/
│ │ └──my_article/
│ │ └──some_picture.png
│ ├── index.md
│ ├── my_article.md
│ └── another_article.md
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.
// 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 proved to be the most complex. 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!
SparkPost is built by and for developers and as such, we value your input. We showed you our true colors during the Mandrill migration and we’ve added lots of new features and enhancements based on your suggestions. We’ve also opened up a communication stream for you to share feedback with us on a regular basis. Now that we’ve gotten to know who you are, we want to pull back the curtain a little and introduce ourselves.
Mark down September 21st on your calendar to hang out with us LIVE and get to know our Dev Relations Team in our new All Things Delivered live stream. In our first live stream find out who we are, what we do, and why we’re passionate about delivering the best email cloud service on the planet to you, our community.
Starting in September, on the third Wednesday of every month, we’ll be coming to you LIVE for 30 minutes to discuss what our team is working on and walk you through our client libraries, the SparkPost CLI, or other technical topics. We’ll also be covering common questions and issues that you, our community members, have brought to our attention; helping you troubleshoot issues and get a better understanding of how to look for information that will help you do your job better and land your messages in the inbox.
We’ll also be taking questions from you in real-time via the #SparkPostLive hashtag on Twitter and via the SparkPostLive channel in our Community Slack.
Here are some dates to add to your calendar for All Things Delivered:
- Sept 21, Dev Relations team: Who, What and Why – Add to Google calendar
- October 19, SparkPost API basics & CLI – Add to Google calendar
- November 16, SparkPost Client Libraries – Add to Google calendar
- December 14, Community Driven Roadmap – Add to Google calendar
How can you participate?
If you’re unable to participate live, you can always watch the playback on our YouTube channel.
Looking forward to seeing you soon!