This is the fifth article in a seven-part series of blogs that describe our most recent changes to the architecture and content of our documentation. We focus here on CSS architecture and improving the way we deal with assets.
A search interface is like a jigsaw puzzle. It’s composed of many small parts that, once put together, make a coherent whole. When building a search interface, you’re assembling the pieces and designing the puzzle. There’s no one-size-fits-all solution, only countless possibilities to fulfill unique use cases.
InstantSearch is a family of front-end libraries that provide the building blocks to help you build search interfaces. It gives you infinite possibilities to build the ideal search experience you’ve imagined for your users. In many cases, what you need comes right out of the box, but you can also customize existing widgets or build your own.
Yet, how do you 10x on DX—the developer experience—when documenting such a library?
The challenges of documenting visual components
Written documentation works wonders for renderless software such as API clients or REST APIs. In such cases, meaningful content, handy examples, and a powerful search go a long way.
Documenting UI widgets is another story. When you’re building a user interface, the thought process radically changes. You’re no longer thinking about the data you have or what method you need to perform a task. Instead, you’re pondering about what your search interface should look like, and how your end users can interact with it. Maybe you even have a mockup ready and you’re trying to find the right widget to implement it. In this situation, written documentation falls short. No matter how well you describe a visual component, nothing beats seeing it in action.
We wanted to reverse the traditional documentation pattern for InstantSearch. Instead of letting users search for what they need through guides and long lists of widgets, we thought it would be more helpful to give them an immediate, visual idea of what they can do. We wanted to show widgets in action in a real search interface, and let them access the documentation from there.
So, we built a fully working, interactive showcase of the InstantSearch widgets, and integrated it right in the documentation.
Designing the showcase was a challenge. Nicolas Meuzard, our product designer, had complex specifications to start from. We wanted to display the full library, show each widget’s possible variations, and redirect to their respective documentation pages. However, it also needed to have a cohesive feel: we wanted the showcase to look like an actual search interface. It was important so users could project themselves and quickly know what they need.
InstantSearch is a rich library, so we decided to break down the showcase into three different experiences: a regular full search interface, an autocomplete widget, and a geo search experience.
After several iterations, Nicolas came up with a design that seamlessly integrates into the docs. It lets you switch between three views, and displays each widget (or group of widgets) as dotted blocks. When you hover any of them, you reveal a link that redirects you to their documentation.
Building the showcase
The InstantSearch showcase isn’t the first interactive tool we’ve built for the docs. Before that, we developed a dynamic filters syntax validator and an interactive tutorial. Both times, we’ve assessed it’s a much better idea to keep these tools separate, in their own repositories, and find a way to integrate them in the docs, instead of shoving everything in the documentation repository.
For the showcase, we decided to go with Vue.js as we did for the interactive tutorial. We serve the app on a separate S3 bucket and integrate it into the docs website using an
The implementation itself was quite straight-forward. We use Vue InstantSearch to display widgets, which does most of the heavy lifting for us. However, it did come with a few interesting challenges.
One showcase for all
It was clear to us that we should build and use a unique showcase for all InstantSearch flavors. This is easier to manage and maintain. However, we also needed to take those specificities into account without cluttering the code.
We have a relatively low number of different flavors, and they don’t diverge too much, so we decided not to over-engineer and went the simple path. Since we embed the showcase in the documentation with an
iframe, we also pass the current InstantSearch flavor as a query parameter. If you’re visiting the showcase from
/doc/guides/building-search-ui/widgets/showcase/react/, the showcase, therefore, receives “react” as the current flavor, which allows it to apply conditional logic.
Handling conflicting widgets
Some InstantSearch widgets serve similar purposes, so we needed to find a way to display them all to users without cluttering the UI. For this, Nicolas came up with a switcher pattern. We group all similar widgets into the same block, we display all titles, and we let users click on them to switch.
Yet, sometimes, these widgets have incompatible behaviors. This means you can’t have them all in the same UI at the same time.
We solved that issue by using dynamic components, a Vue.js feature that lets you load components on the fly, at runtime. We’re only showing a single widget at a time, so instead of showing it and hiding the others, we can leverage dynamic components to swap between widgets by destroying the former and mounting the new one.
Guessing the height
One of the challenges with using an
iframe is how to handle content with variable height gracefully. In our case, the showcase loads dynamic content (search results) and therefore changes height when you perform a search, load more hits, switch to another experience, etc. Unfortunately, from the outside, it’s impossible to detect that the height has changed.
We circumvented this issue by leveraging the
window.postMessage method, which lets us establish communication between the docs and the showcase. Vue.js provides an
updated lifecycle hook which fires every time the DOM re-renders. We use this hook to emit the new height of the body whenever the showcase changes. The website listens for new messages and updates the height of the
iframe whenever it receives a new height.
The showcase is a direct corollary of the InstantSearch widgets list but visually. It helps discover InstantSearch without feeling overwhelmed by the amount of choice. It also helps users being more productive by not having to browse widgets to find what they’re looking for. Funny enough, several of Algolia’s solutions engineers and sales representatives now use the showcase when pitching InstantSearch to prospects 🙂
Of course, none of this could have happened without robust processes in place. This is what our next article covers, so stay tuned!