How Mailjet sped up searches in its documentation with Algolia’s DocSearch

Have you ever developed an API by yourself? The task can be cumbersome, to say the least. Sure, you’ve written clear and maintainable code. You’ve even implemented unit tests. And now, you are ready to promote your API with all of your future fans. But, as you’re about to share it with the world, you start to wonder whether it will get traction. To better your odds, documenting your API with clear and concise information is a must-have, but how can you ensure people will be able to easily find what they need?

Speeding up searches in Mailjet’s documentation with Algolia’s DocSearch

Here at Mailjet, we take documentation seriously. We have several APIs, and for each of them we have written a detailed guide based on our users’ feedback. Everything is illustrated with snippets in PHP, Node.js, Ruby, Python, Go and Java.

Think that’s it?

Hum, not so fast Tuxedo Mask! OK, our documentation has always been very detailed, but it was also very heavy. To generate it, we use Slate. Fast, reliable and good looking, it has some nice features, like out-of-the-box syntax highlighting or an automatic, smoothly scrolling table of contents. But, sadly, its internal search engine is a nightmare when it comes to working with big documentation. So, we had to look for an alternative.

And this is where Algolia comes in.

Algolia: search engine as a service

Algolia defines itself as “a Hosted Search API that delivers instant and relevant results from the first keystroke”. Another SaaS application you’d say? Yes, but it stands for Search as a Service (see what we did there? 🤓). Fast and reliable, it’s probably the service you want to use when you integrate a search tool on your website. Some of our favorite websites, like ProductHunt, Twitch, Medium or BlaBlaCar, already trust it.

OK, so you want to try it out? Thought you would. ;)

To use Algolia at its full potential, you’ll have to select a paid plan, but they also provide their community with awesome free tools and very cool open-source libraries. The one that fits our needs is called DocSearch, a free and smart solution that has helped us turn our documentation into something much more manageable.

Used by libraries such as ReactJS, Babel or GraphQL, it’s definitely the easiest way to add search to your documentation. We just had to fill the form with a link to our online documentation and an email address and voilà! We received a code snippet that was just seven lines long, ready to integrate into our HTML layout.

To be honest, this wasn’t totally la vie en rose. During the integration process, we encountered a bug (basically, a few keywords weren’t found automatically) and we had some trouble figuring out if everything we wanted to achieve was possible (we have high expectations, you know); but each of these issues was addressed very quickly by the Algolia team.

Today, even if we’re still using Slate to render our documentation, dropping their search engine and opting for Algolia’s DocSearch has clearly improved the overall performance of our documentation. That doesn’t mean every issue’s been resolved, though. Our documentation’s loading time could still be improved. We like things to be quick and easy and we want to provide our dev users with a blazing fast tool, so this is the next challenge in our to-do list.

Have you checked out our documentation? Do you have any advice or feedback? Share it with us on Twitter, and don’t forget to check out our community page to get the latest news and interact with us.