Design and audit documentation search and discovery systems including federated search, scoped search, CMD+K patterns, synonym handling, zero-result recovery, and search analytics feedback loops. Use when building docs search, reviewing search UX, fixing zero-result rates, or optimizing content discovery. Triggered by: search, docs search, federated search, CMD+K, search UX, synonym, zero results, search analytics, content discovery, search design, scoped search, search-to-click, findability, search bar, autocomplete, search relevance.
Design and audit the search and discovery systems of a developer documentation site. Search is the escape hatch when navigation fails — and for 40-60% of developer docs users, search is the primary navigation method. This skill covers search UX patterns, relevance tuning, synonym management, and analytics feedback loops.
This skill handles search and discovery mechanisms. Navigation structure is handled by designing-navigation-systems. Content categorization is handled by governing-taxonomy.
Research shows developers split into two navigation styles:
| Style | Behavior | Percentage | Implication |
|---|---|---|---|
| Link-dominant | Navigates via sidebar, links, breadcrumbs | ~40-50% | Invest in navigation structure |
| Search-dominant | Goes directly to search, ignores sidebar |
| ~40-50% |
| Invest in search quality |
| Mixed | Uses both depending on familiarity | ~10-20% | Both systems must work |
Key insight: You cannot choose between good navigation and good search. Both are required.
The modern developer docs search pattern: keyboard-activated modal search.
| Element | Specification |
|---|---|
| Activation | Cmd+K (Mac) / Ctrl+K (Windows/Linux) |
| Visual | Modal overlay with input field, centered |
| Placeholder | "Search docs..." or "Search [product] docs..." |
| Results | Appear inline as user types (no page reload) |
| Navigation | Arrow keys to select, Enter to navigate, Esc to close |
| Shortcut hint | Show ⌘K in the top bar search input |
CMD+K Requirements:
| Element | Rule | Anti-Pattern |
|---|---|---|
| Title | Page title, highlighted match | Full URL path |
| Snippet | Context around the match, bolded keywords | First 100 chars of page |
| Breadcrumb | Show section path below snippet | No location context |
| Icon | Indicate content type (guide, reference, API) | No visual differentiation |
| Grouping | Group by section or content type | Flat ungrouped list |
| Factor | Weight | Rationale |
|---|---|---|
| Title match | Highest | User often searches for page titles |
| Heading match | High | Section headings indicate topic coverage |
| Content match | Medium | Full-text relevance |
| Page popularity | Low boost | Popular pages are more likely targets |
| Recency | Low boost | Recently updated content may be more relevant |
| Content type | Contextual | Tutorials rank higher for beginner queries |
Allow users to narrow search to a specific docs section.
| Scope | When Useful | Implementation |
|---|---|---|
| All docs | Default, broadest search | No filter applied |
| Current section | User is already in the right area | Filter by sidebar section |
| API Reference | Looking for specific endpoint/parameter | Filter by /reference/ path |
| Guides | Looking for how-to instructions | Filter by /guides/ path |
┌─────────────────────────────────────────┐
│ 🔍 Search docs... ⌘K │
│ ┌─────────────────────────────────────┐│
│ │ Scope: [All Docs ▼] ││
│ │ ├── All Docs ││
│ │ ├── Current Section ││
│ │ ├── API Reference ││
│ │ ├── Guides ││
│ │ └── Tutorials ││
│ └─────────────────────────────────────┘│
└─────────────────────────────────────────┘
For products with docs spread across multiple sources (docs site, API reference, changelog, blog, community forum).
User Query
│
├──→ Docs Index ──────→ Results (primary)
├──→ API Reference ───→ Results (secondary)
├──→ Community/Forum ─→ Results (tertiary)
└──→ Blog/Changelog ──→ Results (lowest priority)
│
└──→ Merged, Ranked, Grouped Results
| Rule | Rationale |
|---|---|
| Docs results always appear first | Core docs are the primary resource |
| API results in separate group | Users know when they want API vs prose |
| Community results labeled clearly | User-generated content has different authority |
| Blog results appear last | Often outdated, not the canonical source |
| Each source shows max 3-5 results | Prevents one source from drowning others |
Users search with their vocabulary, not the product's vocabulary. Without synonym handling, a search for "login" returns nothing when the docs use "authenticate."
| Type | Example | Handling |
|---|---|---|
| Conceptual synonym | "login" ↔ "authenticate" | Bidirectional mapping |
| Abbreviation | "k8s" ↔ "kubernetes" | Expand abbreviation |
| Version name | "v2" ↔ "current" | Map to canonical version |
| Colloquial | "env var" ↔ "environment variable" | Expand informal term |
| Competitor term | "Heroku dyno" ↔ "[product] worker" | Map competitor vocabulary |