Search Best Practices for Documentation Sites
Search Best Practices for Documentation Sites
Good search helps users find answers fast. Here are practical tips for HermesDocs and docs sites in general.
1. Write Descriptive Titles and Descriptions
The search index uses title, description, and content. Clear, keyword-rich titles and descriptions improve relevance. Avoid vague labels like “Overview” or “More Info.”
2. Use Consistent Terminology
Pick one term for each concept and use it everywhere. If you call it “API key” in one place and “access token” in another, search won’t connect them unless both appear in the same page.
3. Structure Headings for Scannability
H2 and H3 headings become table-of-contents entries and search snippets. Use descriptive headings that summarize the section so users can skim results.
4. Algolia vs Client-Side Search
HermesDocs supports both. Client-side search works out of the box with no setup—great for small docs. For large sites (100+ pages), Algolia scales better and offers typo tolerance and analytics.
5. Test Your Queries
Search for things your users would ask. “How do I reset my password?” “Where is the API key?” If those queries don’t surface the right page, refine the content or add an alias/redirect.