Building a knowledge base people can actually search

Search quality begins before a search provider indexes the site. It begins with how documentation is divided, named, described, and connected. A powerful engine cannot rescue content that hides several unrelated tasks behind vague language.

Understand search intent#

Readers search with a goal and a vocabulary shaped by their current problem. The query often describes a symptom rather than the product concept that causes it.

Collect real queries

Use search logs, support tickets, community discussions, and sales questions. Group variations that express the same intent, then compare those phrases with the language used in documentation.

Separate query types

Navigational queries seek a known page. Task queries seek steps. Diagnostic queries describe failure. Concept queries ask how something works. Each type benefits from a different result shape.

Create focused pages#

Search works best when a page has one primary job. Broad pages may rank for many terms but force readers to hunt through unrelated sections.

Set page boundaries

Split a page when sections answer independent queries, target different audiences, or change at different rates. Keep a sequence together when later steps depend on earlier context.

Avoid thin fragments

Do not create a page for every sentence-sized answer. A useful result includes enough explanation, prerequisites, examples, and next steps to complete the reader's task.

Write searchable titles#

A title should identify the object and the action or concept. Put distinctive words early so they remain visible in narrow result lists.

Prefer reader language

Use the terms readers type, then introduce official product terminology in the page. Internal labels with no external recognition reduce retrieval quality.

Distinguish nearby pages

Titles in the same section should not differ by one vague adjective. Make the unique task visible, such as “Rotate API keys” and “Revoke API keys.”

Build result context#

Titles earn attention; descriptions help readers choose. A useful description clarifies outcome, audience, prerequisite, or limitation.

Write clear descriptions

Avoid repeating the title or promising generic learning. Explain what the reader will be able to do and mention the condition that makes the page relevant.

Preserve useful breadcrumbs

Show enough hierarchy in results to distinguish identical terms across product areas. Breadcrumbs also help readers understand where they landed after opening a result.

Structure page content#

Search engines and readers both depend on headings to understand the page. Headings should form a useful outline even when read without the paragraphs below them.

Use direct headings

Name the decision, task, or state. Avoid clever transitions and generic headings such as “Overview” when a more specific phrase can describe the section.

Answer before detail

Put the direct answer near the top, then add rationale, examples, and edge cases. Readers should not cross a long introduction before confirming that the page matches their problem.

Improve the index#

Good source content still needs a clean search index. Exclude navigation, repeated footer text, hidden labels, and decorative content that pollute relevance.

Index meaningful fields

Store title, description, headings, body, URL, section, and content type separately. Field-aware ranking can value a title match more than a mention deep in prose.

Tune ranking weights

Start with transparent rules. Exact title matches, heading matches, and recently verified content can receive modest boosts. Avoid aggressive freshness that buries stable reference pages.

Measure search quality#

Track whether search helps readers continue, not only whether they click. Reformulated queries, fast returns, and support escalation reveal weak results.

Review failed searches

No-result queries expose missing synonyms, spelling variants, or content gaps. Review them regularly and assign an explicit action: add vocabulary, improve content, or accept irrelevance.

Test representative tasks

Maintain a small benchmark of important queries and expected results. Run it after changing content structure, indexing, tokenization, or ranking logic.

Maintain search trust#

Search trust is cumulative. Clear titles, focused pages, useful descriptions, clean indexing, and deliberate evaluation make results predictable. When readers repeatedly find the right page, search becomes the fastest route through the knowledge base.