How we simplified Mux's documentation search with Algolia DocSearch

Building awesome custom front-end components is kinda like buying a boat. There’s nothing quite like the feeling of crafting a unique, personalized UI that you can make your own and change to your heart’s content. You can move fast, at your own speed. The sunny days spent navigating your user interface with your coworkers are unforgettable. When things are good, they’re good.

But soon… you’re faced with the reality of maintenance. Parts break. The interior decays. You suddenly need to find the time and money to dedicate towards keeping your boating dreams alive. You fondly recall the afternoons spent laughing with your colleagues, enjoying each other’s company, shipping effortlessly, gently bobbing on the once-cutting-edge watercraft that was your UI.

Those days are long gone now. Now, all you do is wish this was someone else’s problem. Maybe you should have just rented a boat from the marina.

At Mux, we faced exactly this scenario with our custom search components on our documentation site. Instead of pretending we are search experts, we recently decided to rip it all out and use Algolia’s DocSearch.

Let’s take a look at some of the challenges we faced with our custom search, our decision to switch and migrate to DocSearch, and the benefits we immediately realized that made our search experience so much better for both our employees and our customers.

Challenges we faced with our custom search

During our docs build process, we used to run a custom script that would sift through all our generated pages and identify the different elements and content that needed indexing. We’d then attempt to retrieve the results for a given query and display them within our own custom UI. There was a lot of effort that went into trying to improve our search experience, but as soon as we’d fix one issue, another one would pop up.

This manual and declarative approach required a lot of attention. That’s a tough ask for a lean team in charge of making our documentation experience as helpful as possible for our customers (and, our employees).

As important as search is, we don’t have a ton of resources to dedicate towards making this critical feature great. Mux is a video company, not a search company. We know firsthand what it’s like to offer a product intended to reduce the complexity and difficulty that your engineering team might run into within a problem space. Oftentimes, the total cost of ownership for managing your own technical infrastructure is hidden under the veil of developer confidence and optimism.

We were proud of the way our search experience looked, but not the way it worked. It turns out search UX is very important, and this is something that Algolia has studied heavily… so we turned to Algolia for a helping hand.

Decision to switch to Algolia’s DocSearch

I’ll be honest: at first, we were a little hesitant to chuck out our custom solution in favor of DocSeach. I always thought DocSearch was the simplest bare-bones solution, almost too simple for our needs. I thought we’d be giving up some of the control or customization. In short, I didn’t think DocSearch was going to work for us. But we were willing to try anything to find better results, so off we went to experiment.

We opened a new branch and started deleting a ton of old code. I’m talking thousands of lines tossed out in favor of a single managed component. It straight up felt like we were doing something wrong. But, after trying it out and learning how it worked, we understood the value of adding DocSearch to our documentation almost immediately.

No longer did we have to pretend to be search experts. Our friend Algolia had our back.

From idea to POC in half a workday

Implementing DocSearch is really as simple as it says on the tin. Drop a component into your application, add your Algolia keys and index ID, and boom, you’ve got search. Right out of the gate, we were able to see improved search results and indexing. It was also clear that the hierarchy provided by DocSearch was going to lead to a more thoughtful presentation of our available guides and references.

For customization, we paired a designer and developer together to conduct an iterative build-in-the-browser process. Our designer would make a few suggestions, and our developer would check the CSS variables to see if there was a way to control the visual output. For areas not covered by the available CSS variables, there was still a way to write our own CSS and get the UI looking like our brand’s flavor.

The crawler config was pretty effective out of the box, but we spent just a few more hours tweaking the results to prioritize specific guides over other materials like changelogs or recipes. We also choose to show our video product guides above our data product, as many folks just getting started are generally looking for help with the initial video integration using Mux.

Taking our new search out for a cruise

It’s hard to believe, but we were able to refactor and ship our entire search stack in one day. The speed was great, but what mattered most would be the feedback we received from our users.

We didn’t have to wait long: we immediately started hearing positive feedback from our employees about the new and improved search experience. One employee even said, and I quote, “I use our docs almost daily and forgot to share appreciation for how incredible this update has been – the search improvements are life-changing.”

No longer did we need to maintain this massive search project on our own. There was a huge weight off our shoulders.

We’re still thinking about ways to continue to improve our search. One idea is to show a sneak preview of what a search result page contains before you actually visit it. This could be anything from a table of contents, to a code snippet, or any other type of preview info. The DocSearch component provides just enough customization to make this idea possible.

Also… DocSearch is free. Like, free free.

Free as in free. This was the proverbial sugar on top. DocSearch costs $0. As long as you’re willing to showcase the Algolia logo in your component, your search experience can be made infinitely better at no cost to you. How’s that for a deal?

Sometimes, rolling your own solution makes sense. In this situation, we learned that we needed to release control and allow the experts to take over and help us out in this problem space. If you’re struggling with search on your side and also have a developer product, you have my full unbiased recommendation to use Algolia DocSearch. Check it out—and get back to focusing on what makes your business unique.