Update Synonyms page, mention UI option #2675
Conversation
🔍 Preview links for changed docs |
leemthompo
changed the title
link fixes: updated custom bundle link to external path fixed api examples link to dedicated page content improvements: clarified step 2 description for analyzer configuration enhanced expand parameter explanation with bidirectional vs canonical mapping examples removed redundant phrases and improved conciseness fixed spacing in synonym file examples reorganized token filter section for better flow streamlined synonym rules introduction
There was a problem hiding this comment.
Overall changes LGTM for structure and API. Left a few comments, will defer to @efegurkan for UI feedback
|
|
||
| There are two main formats for synonym rules: | ||
|
|
||
| **Explicit mappings** use `=>` to specify exact replacements: |
There was a problem hiding this comment.
Do we want to drive the point home here, where sea biscuit will be mapped to seabiscuit but seabiscuit will not be mapped to sea biscuit, but that ipod maps to i-pod and i-pod maps to ipod?
| Synonyms are grouped together using **synonyms sets**. You can have as many synonyms sets as you need. | ||
| You have multiple options for creating synonym sets and rules. | ||
|
|
||
| ### Synonym rule formats |
There was a problem hiding this comment.
It's a little odd placement here to say "This is how you create synonyms sets" and then go into the format definitions. Maybe this could come above the step by step instructions?
There was a problem hiding this comment.
Agreed — moved in af28c81
| sea biscuit, sea biscit => seabiscuit | ||
| ``` | ||
|
|
||
| With explicit mappings, the relationship is one-way. In the previous examples: |
|
|
||
| Your synonyms sets need to be stored in {{es}} so your analyzers can refer to them. There are three ways to store your synonyms sets: | ||
| 1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](/explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects) |
There was a problem hiding this comment.
I think our style rule is to include terminal punctuation if the list item is a complete sentence -- also item 5 does have a terminal period but the others don't
There was a problem hiding this comment.
this was a test and you passed Marci 👍 😄
|
|
||
| To use synonyms in {{es}}, you need to follow this workflow: | ||
|
|
||
| 1. **Create synonym sets and rules** - Define which terms are equivalent and where to store your synonym sets |
There was a problem hiding this comment.
Add terminal punctuation to these list items; also I'd do colons after the bold labels, instead of hyphens/dashes
leemthompo
changed the title
closes https://github.com/elastic/docs-content-internal/issues/201
• Restructured content flow - Moved duplicate heading, consolidated sections into logical workflow steps
• Added step-by-step workflow - Organized synonyms usage into 4 clear steps: create rules and sets → configure analyzers → test → apply
• Enhanced synonym rule documentation - Added detailed explanation of explicit mappings vs equivalent synonyms with examples
• Added Kibana UI method - New section documenting UI-based synonym management (serverless only)
• Improved method organization - Restructured storage options as numbered methods (UI, REST API, File-based, Inline)
• Added warning context - Enhanced warnings about synonym rule errors and their impact
• Clarified search-time limitation - Added note that API/UI-created synonym sets only work at search time