Paul Jankowski 0:15
Welcome, everyone. Thank you for joining me on this quest to discover a great search experience. My name is Paul Jankowski. And I work at Algolia. I’m a software engineer on the developer experience team. And my job is to make developers lives easier. This can come about in multiple ways, such as doing a talk like I am today. But most of the time, it involves writing code and the documentation that goes along with it. Today, I wanted to walk through how I went about adding content search to my documentation platform. Let’s take a look at what I started with and get a sense of what needs to be done to improve on it. As you can see, this is a fairly slow experience requiring me to have the full query entered before even starting to fetch results. And as we do, we have to stare at this ugly Spinner for far too long. But now that we have some results, we can see they’re a little all over the place. We have unrelated hits like getting started and Java scripts set timeout. And we also have duplicated hits like invalidating a cache, which I know is one of the hardest things in computer science. But I really don’t think it needs to be here twice. Plus, if I were to come here and select one of these, it doesn’t even take me to the right page. Overall, this is frustrating. And I don’t know if a user is going to be able to find what they’re looking for at all. So what do I need for a better search experience? Well, there are three main parts that I like to think of, I need to have content. This is the reason for search in the first place, I need to have a polished UI. And I need it to be relevant. So I can make it faster and easier for readers to find exactly what they’re looking for. Of course, there is a lot more to it than just that. Things like accessibility, speed filtering, and much, much more. But these are the three main areas of concern I like to focus on.

Paul Jankowski 2:46
Let’s dive deeper into each one of these to get a good understanding of what they represent. Content is king, the value of your website is in its content. And you should want people to be able to search for it. We spend a lot of time crafting the right information and content for users to get what they need. Our search should reflect that as best as it can. Which presents an interesting thought, how do you store your content in a searchable way? Do you manually edit a JSON file? Or do you have a script that publishes to a database? Or do you just offload everything to a CMS? What about when content gets updated? or new members? join your team and don’t know your process Exactly. How do you prevent your content and your search data from getting out of sync? I tend to reach for a crawler solution. When working with a content heavy platform. A crawler allows you to focus on your content, writing it once and handling updates as you make them. It can crawl your live site, copy over your existing hierarchy and content that you’ve already put so much thought into. This way, any update you make is automatically transitioned into your search experience. As for the UI, I need it to be available to users so they can get in, find their information and move on with their task at hand. This can take many different shapes depending on your project. But the important part is that it’s made available to all users and is a joy to use. For my UI, I built an improved solution using shad sciennes UI toolkit. This makes it more accessible with keyboard shortcuts and proper focus management. And after all, the more accessible means the more users that have a chance to use more I search, it’s giving me somewhat relevant results as soon as I started typing, making it so user can get to where they need to go much quicker. And overall, it just seems like a much better experience. Now, for relevancy, the hardest part of it all, there’s a lot of moving pieces here. Should one result be displayed before another? A match in a title is surely more important than a match in a footnote? Do you need to take into account the last time a page has been updated? These are all important questions to think about when surfacing results to a reader. There’s a lot going on under the hood. And all of that needs to be invisible to the user and just work. I like to think of relevancy, kinda like a joke. If you have to explain it, then it probably wasn’t very good. If your users are questioning why certain results are being shown to them, than your relevance isn’t doing a good job. If it’s done well, they’ll be able to find their results faster, and with ease, never questioning why a certain result showed up for a certain query. Although relevance can be hard, we do have some tools to help us out. We can use hierarchy to help denote importance between results and ranking to maybe have popular searches hold more weight and appear at the top of the list. Or synonyms to help aid and typo tolerance, and allow users to find what they’re looking for. Even if they don’t know the exact name or phrase. With these tools, relevancy becomes less scary and a valuable asset inside of your search. Let’s take a look back at my documentation now that we understand a bit better of what makes a great content search experience. The UI is much more available, using the command K shortcut. And being accessible with quick escape to close or clicking outside of it. As I started typing, I’m starting to get results immediately. They may not be the most relevant, but they’re doing the best they can to try to hint at where I might want to go. As I finish up my search, you can see we now have a hierarchy forming, which comes exactly from my content, exactly how I wrote it. So if I come down here to Redis as a driver prerequisite, it’s going to take me exactly to that place on the page. And I can start reading and gaining information immediately. Now that seems like quite a bit better of an experience than what we had prior.

Paul Jankowski 8:05
These are just the types of things that we at Algolia are always thinking about. It’s why we built a First Class Search API for developers. If only we could package all of these things that we talked about today into a single package to make content search fat much easier for developers. Well, we did, we went out and we built doc search, we assumed that we were not the only ones that are having issues looking for relevant information, and documentation pages or blogs. So we packaged our powerful automated web crawler, and built a fast and sleek UI. The features highlighting typo tolerance, ranking based on the page hierarchy and much, much more. The best thing about it is it’s free for any technical knowledge sharing website. This could be a documentation site, a technical blog, or even an ebook site all about systems design. You can check out Doc search.algolia.com To learn more, if you’re interested. Thank you so much for coming on this journey with me today. I hope we all learned about what makes a great content search. My name is Paul Jane kowski. And I hope you have a wonderful day or evening. Goodbye