Software engineers can have a significant impact on whether their company uses a tool or software. Consequently, improving your product’s developer experience is essential – especially in areas designed for developers, such as documentation and API references.
An integral feature of any documentation is search. And the more information your documentation provides, the more critical good search becomes.
Let’s take a look at what makes API documentation search so important, how to provide the ideal search for technical audiences, and what best practices to follow.
Table of Contents
Why build a great API search at all?
For many tech teams, a product’s API reference and documentation is essential when making a purchase decision. Developers must be able to imagine working productively with your product or service. Naturally, poor documentation doesn’t contribute to efficient workflows – but well-structured, thorough, and searchable documentation does.
In most cases, though, developers visit documentation because they face a challenge and need help solving it. So they already have a question in mind and use search to find the required answers.
Yet, with poor API search, they often have difficulty finding relevant documentation articles, or it takes way too long. As a result, users get frustrated and reach out to your support staff to resolve the issue. But shouldn’t documentation reduce such inquiries?
All in all, the ideal search should provide developers with the information they need as quickly and conveniently as possible. In this way, you can sustainably increase the developer experience with your product and API, cut help desk costs, and free up support staff time for other tasks.
5 ingredients for great API search
Let’s take a look at five documentation search best practices that you can use to streamline your API reference and boost developer satisfaction.
Categories and filters
The more extensive your API reference and documentation, the more organization it needs. Your documentation may also contain other topics and information in addition to the API reference. So if you cover information on different products, API versions, topics, content types, and so on, you need to provide tools for the user to narrow down their search.
Categories help the user to quickly distinguish between different topics. Suppose your documentation contains different versions of your API. A developer currently using API version 1.2 would only want to search the documentation for that version.
Or let’s say your documentation includes API references, tutorials, and getting started guides. When a developer wants to read tutorials, they want to limit the search to get results from only that category.
The Photon documentation search uses filters to let users limit their search to specific categories:
Depending on your use case, it can make sense to add more filters and enable faceted search. Users don’t always use perfect keywords in their searches, and they may not be so sure about the exact content they are looking for. Faceted search helps educate users about your documentation’s contents and enables them to find relevant information by specifying their interests.
Here’s an example of how documentation search could look like on different topics using categories and facets:
AddSearch tip: Ensure that you only display the required number of filters and categories. Too many options can clutter and over-complicate your search. By monitoring and analyzing the search behavior of your users, you can find the optimal way here.
Color codes
Color codes are a great way to help readers differentiate between categories even faster. It’s no coincidence that hospitals and airports assign colors to specific areas to help people find their way around and not get lost.
In comparison, navigating documentation is likely to be less of a problem for most developers. However, you can significantly improve the developer experience by color-coding certain areas.
For example, you could assign each product, API, or category a different color. That way, the reader can instantly spot whether they’re on an API reference article, a community forum post, or the upgrade guide.
AddSearch tip: We recommend not going into too much detail when it comes to color-coding. Using too many colors is pointless if no one can remember them. Also, make sure the colors are distinguishable, test for color blindness, and check the contrast for accessibility.
Bundled knowledge
Do you provide helpful information about your product and APIs in many places? Then it can be handy to bundle all sources in your documentation search and display search results from these different areas.
For example, user support forums are a great place for developers to help each other, share experiences, and answer questions about a product. Since your documentation can hardly provide relevant information for every use case and problem, you could include these forum posts in your documentation search. This can improve the search experience and increase the likelihood that developers will find the answers they’re looking for.
Think about providing users with a unified search experience across different sources on your websites or even across domains. This allows you to cover various content types in one search, such as API documentation, user support forums, blog posts, video tutorials, etc.
On the screenshot below, you can see an excellent example of documentation search bundling different content types from different origins:
AddSearch tip: Use filters and color codes that help differentiate between knowledge resources and their origin. This can improve the user experience of your search and help users find their way around more quickly.
Speed and ease of use
Performant websites and web apps are a must, and users expect your documentation to run at the same speed. But not only should every reference article load at lightning speed, but your API search must also provide visitors with valuable results as fast as possible.
For this, autosuggest is an absolute lifesaver. Once the user types in a few letters, the search already shows a list of matching results to choose from. Ideally, developers can immediately spot a promising document in the list, click on it, and get the information they need. You can see autosuggest in action on Vaadin.com’s documentation search:
AddSearch tip: If you want to make developers even happier with your search, let them select search results and autosuggestions from the keyboard. If they don’t have to switch between keyboard and mouse, your search may appear even faster, more efficient, and less complicated to them.
Relevant results
On websites, you often want to promote specific search results and influence what content the search engine should consider relevant. For this reason, reasonable search solutions offer you a way to configure and adjust search results accordingly.
For documentation, things often look a little different. In most cases, you don’t have specific pages that are more important than others from a business perspective. Yet, some sites are more popular with users than others. Naturally, knowing your users may give you an idea of what interests them and prioritize search results based on those insights.
However, a more effective way of doing this is to leave things to an algorithm. For example, our self-learning AddSearch algorithm monitors which search results users prefer for which keyword and then adjusts the order in which search results are displayed.
Suppose the 5th result for the search term “authentication” is clicked the most. Then the algorithm makes sure that it appears higher up on later searches for the same keyword.
Our algorithm helps you ensure that users find what they’re looking for without investing a lot of time and effort. This is particularly useful for popular keywords that appear in many documentation articles but are not equally important to users. Instead of searching through a massive list of search results, users can conveniently find the most critical results listed at the very beginning.
How to build the ideal API search?
Finally, we’d like to give you a rough guide on the steps required to create the ideal search for your documentation. To that end, we recommend checking out our blog post, “How to add a search bar to your website,” which covers the topic in more detail.
Plan, research, and set goals
Put your team together and start the project with a thorough planning phase. Review your documentation, your various content types, API versions, categories, and other knowledge resources that you provide. Feel free to get outside inspiration and make sure you plan the ideal search that helps developers and your company achieve their goals.
Speaking of goals, it also makes sense to set some goals for your API documentation search. You may want to use search to reduce help desk costs, or you may want to reduce the time spent on particular pages and lengthen it on others, etc. Depending on your use case, your goals can look completely different. That is why it’s essential that you take your time during this phase and get a clear picture of your future search.
Create wireframes, define search features, and index content
Wireframes give you a solid idea of what your future documentation search will look like. Take all your findings and goals from the planning phase into account to define the required search features and integrate them into your wireframes.
We recommend again that you make full use of the time during this phase to experiment!
In parallel, make sure that you can index your content in a searchable manner. AddSearch offers you two options here:
- Our web crawler automatically indexes your documentation, which is quick and easy. You may only need to change your content structure to expose specific data, such as categories, to the crawler.
- Use our Indexing API to manually store content in the search index and fully control how data is stored. This option is particularly effective for complex or extensive documentation. For example, suppose your API reference covers many topics on a single page (under one URL). Then you can use the Indexing API to divide this page into subpages to make them easier to search for.
Whichever option you choose, organizing your content logically and consistently is the basis for every successful documentation search. Also, well-structured content with pages, headings, fields, and dedicated areas for code snippets is more convenient for the human eye to scan and read. So, dealing with this topic in more detail definitely pays off!
Implement, release, and monitor your search
With the wireframes at hand and your content in the search index, you now have everything you need to build the search interface. As an AddSearch user, you can leverage our Search UI library to help you build the UI fast, including features for filters, instant results, and autosuggest.
Finally, all you need to do is put the finishing touches to your search, blend it with your documentation design, and make it available to the public!
After you’ve invested the time and effort building a great search, it would be a waste to leave it as is. Instead, you should check analytics metrics regularly to see how users are doing with the new documentation search and then tweak it. Remember to see how search helps you achieve your goals and if you need to take any extra steps.
Back to you
Good API search doesn’t come off the shelf – like any other site search, you need to build it to suit your specific use case. Follow the best practices and steps to create the ideal documentation search from this blog post to increase your product’s developer experience.
We’re excited that companies around the world are using AddSearch to power their API documentation searches. If you’d like to learn more, please contact us to speak to one of our search experts about your needs.
