Developer eXperience, known as DX, is key to building great software, as it helps your developer-users leverage the best out of your software.

Part of good DX is searching through documentation, not only as a means to finding information, but also as a tool to structure technical content. In this article we show you a how a simple project – Algolia’s free DocSearch platform – has come to solve a common pain point in the open source community: that of searching and structuring documentation. We show the positive impact of DocSearch as well as the cost in developing it.

We also focus on the value of search as compared to the widely used Ctrl+F. 

Finally, we present some ideas we have about how to make DocSearch even more helpful.

Making Documentation Easy for Developers

The developer community is growing fast. Their impact is broader and stronger. We wanted to use our search technology to help developers do their magic and make this world a better place. It was time to focus on a proper DX. 

That’s where Algolia and its DocSearch tool comes in: making search come alive with a learn-as-you-type experience.

Search solves a regular issue: every developer needs to use documentation whenever they need to learn or use new technology. Search brings love to a project. But most projects have limited resources, or they lack the knowledge to create a good search experience for their documentation. They focus on building an amazing tool. DocSearch makes their documentation come alive – for free and out of the box. 

DocSearch has been warmly welcomed in the community. It proudly helps 2.3 millions unique users a month.It is self-serve and customizable, a complete out-of-the-box experience. It is adaptable to any software, like Stripe, React, and jQuery. Instead of guessing or leafing through pages, your users will leaf through instant search results. It also captures analytics that are key to understanding what your users do and need. You are now data driven to produce great documentation. 

But DocSearch also raises the bar of modern documentation, it standardizes a well-structured approach to documentation. It does this with its crawling mechanism, which its uses to add search to your website. Crawling documentation requires content to follow a certain structure. 

We also improved DocSearch over time. In searching and structuring content, we encountered some fundamental and eternal developer-issues. The biggest one being to choose between space or tabs to indent a page. This was the only negative feedback we had when we integrated DocSearch to jQuery. But we solved this issue, thank to a simple PR:

Why is Ctrl-F Not Enough?

Why go that far with DocSearch when people can just as easily use Ctrl-F? There are many reasons for this:

• You’ll search the entire documentation site instead of only one downloaded page.
• Learn-as-you-type experience. Instant search results and a categorized dropdown box enable users to not only search but browse, discover, and learn. We have noticed that people rephrase, correct, and erase their initial search due to what they learned during the search.
• Speed. In moving from page to page and quickly finding what you need. Millisecond matters.
• Typo tolerance. Our search corrects wrong queries and mistypes. This is key when you search for unknown concepts or technology
• Tie-breaking algorithm. This unique concept of Algolia helps the maintainer better redirect their users, helping their users in an interactive way. Less need for support!
• Analytics. Our search helps you understand what your users are doing. 

Let’s See How it Works

We crawl our 1600+ DocSearch websites every 24H to keep the search synchronized with their content. This process requires a strong and secure infrastructure. We use an infrastructure that scales since we are only at the beginning of the road. This where Kubernetes steps in. Kubernetes (K8s) is an open-source system for automating deployment, scaling, and managing containerized applications. It is now the basis of DocSearch’s daily crawls of over 1600+ documentation websites. If you want more details regarding the architecture chosen, please ping us 🙂

All this comes with a cost. For sure, this project requires a strong and reliable codebase. It all started during a vacation/off site in Porto, Portugal. This is a classic story that we will explain in another blog. Like every project, time is key. We have one main motto on our team: automation! We’ve even built a complete tool that gathers public data about projects in order to provide the best customized help. This too makes for a good blog, which is on its way. To automate properly, we needed to refactor every piece of our tooling. This point is key and helped us ship out our search experience quicker, stronger, and further. 

DX matters even in how we deliver it. We help every compliant project that reaches out to us. However, we’ve noticed that the best way to help big projects is to reach out ourselves. We are hiring to help us with that. Future users of DocSearch only need to click on the “merge” button to see the learn-as-you-type experience alive and in action.

Next Steps for DX

The stable state of our project encourages us to go even further. We always want to show the huge love we have for the community. The road will be long and amazing. We are looking forward to it and we have defined some future additions to DocSearch.

• Better analytics.
• A new version (v3) of the UI.
• Real-time: only crawl website when triggered (that is, when content has changed).
• Dashboard: Let our users create their own configuration thanks to a UI dashboard.
• Improve and make our DocSearch Hub public.

Happy coding and writing great documentation!