Optimizing for searchability and retrieval (for standard and AI search) – Best Practices

Increase the effectiveness of your site’s search and make sure that relevant information is retrieved and surfaced for your users in your help center site.

Search in your Scroll site works best when your content is written and structured with searchability in mind. This article covers the practical levers you have as a site admin or content author, from making sure your content reaches the search index to writing articles that both standard search and AI search can retrieve accurately.

To understand how the search itself works, see How Does Search in the Help Center Theme Work?

Publish Your Site Before You Check Search Results

Search results reflect the last published version of your Scroll site. Confluence edits that you haven't published yet don't appear in your site's search.

If you have recently edited or added pages, update your site before you check whether the new content is findable.

Your Scroll site's search is completely separate from your Confluence search. A page that's findable in Confluence isn't necessarily findable in your site.

Check Exclusion Labels If a Page Is Missing From Search

If a page never appears in search results, check its labels and the labels of its parent pages. Three labels remove a page, and all of its child pages, from the search index:

scroll-help-center-exclude-page - The page stays published and reachable by URL, but is removed from navigation and search. Works only with the help center theme.
scroll-sites-only-url - The same behavior, and works with any theme.
scroll-sites-no-publish - The page isn't published to your site at all.

Because the label applies to child pages too, a page can disappear from search because of a label applied several levels above it.

Learn more about how to Exclude Articles From Navigation and Search and how to Prevent a Page From Being Published.

Include Key Information in Article Title and Body

Make sure that relevant information isn't just included in the title but also in the body of the article, and vice versa. It's always a good idea to start an article with an introductory text that summarizes the purpose of the article and the contents that follow.

For standard search, keyword hits in the title are weighted higher than in the body of the article. However, including the same information in the body increases the quality of AI search responses and makes the article easier to understand for users.

If a page consistently fails to surface for a term your users search for, check whether that term appears in the title. Renaming the page is often the fastest improvement you can make.

For more on titles, see Page Naming Conventions for Better Searchability in Confluence on our Confluence Collaboration Hub.

Create Concept Pages and Add Definitions

Make sure to create concept pages for the concepts you introduce in your documentation or at least make sure that all concepts are defined somewhere in your content. This is especially relevant for those concepts that are unique to your offering.

Creating definitions is important in order to increase the quality and accuracy of AI search responses.

Use Terminology Consistently

Use terminology, especially keywords of your documentation, consistently across your articles. Additionally, sprinkle in synonyms and related terms next to your terminology.

Using synonyms will make your search more flexible as it allows for cases where users use terms that deviate from those you use in the documentation.

Synonyms matter for another reason: search matches whole words only. A page that only ever says "rescheduled" won't be found by a user searching for "schedule." Where you expect users to search with a shorter root form, include that form explicitly.

Make Knowledge Explicit

Users will often search for information that you might consider to be generally known or obvious.

As experts of the matter at hand, don't assume too much knowledge from your users when writing your articles. This means you should almost always assume that users don't have implicit knowledge of or experience with a concept or process and explicitly define and explain these in your documentation.

To avoid cluttering your documentation, it's a good idea to keep this basic or introductory information separate from what you define to be the core content of your documentation. You can separate this information out into its own articles or even its own page trees.

Being able to access foundational knowledge or knowledge that underlies your core documentation will help the AI search return accurate answers and allow your users to apply the knowledge.

Structure Articles With Short, Clearly Labeled Sections

Break your articles into short sections with headings that describe what each section covers. Aim for one idea per section and paragraphs of two to four sentences.

The search results page shows a snippet of the matching text from each article. Clearly structured articles make that snippet easier to read, and make the article easier to scan once your users land on it.

What You Cannot Change About Search

Some search behaviors are built into Scroll Sites and can't be configured per site:

Multi-word queries use OR logic. A search returns every page containing any of the entered terms, not only pages containing all of them.
Quoted phrases aren't supported. Search ignores the quotation marks and treats the phrase as separate words.
Partial matches aren't supported. Search matches whole words only.