From e32f72e49c39c7eff0329a9579fec8714d038f8d Mon Sep 17 00:00:00 2001
From: Jon Bratseth <bratseth@gmail.com>
Date: Mon, 24 Aug 2026 09:50:27 +0200
Subject: [PATCH] Improve 'alternatives' doc

---
 en/reference/querying/yql.html | 38 ++++++++++------------------------
 1 file changed, 11 insertions(+), 27 deletions(-)

diff --git a/en/reference/querying/yql.html b/en/reference/querying/yql.html
index 48fb853faa..b12a4d61af 100644
--- a/en/reference/querying/yql.html
+++ b/en/reference/querying/yql.html
@@ -448,40 +448,24 @@ <h2 id="where">where</h2>
   </tr>
 
   <tr><th>alternatives</th>
-  <td>
-    <p id="alternatives">
-      Use <code>alternatives</code> to provide alternative terms, with an exactness score, to improve recall.
-      Think of it like a special case of the <code>or</code> operator.
-    </p>
+    <td>
+      <p id="alternatives">
+        The <code>alternatives</code> operator is used to provide multiple variants of a token at the same
+        position in the query. The token alternatives are given with a normalized exactness score denoting the extent to
+        which they mean "the same thing" as the first alternative.
+      </p>
 <pre>
 where fieldName contains alternatives({"sneakers":1.0, "shoes":0.7})
 </pre>
+    </td>
     <p>
-      In <code>alternatives({"sneakers":1.0, "shoes":0.7})</code>, each number is an exactness score for that specific word form,
-      not a term weight in the usual boosting sense:
+      The query will match documents containing any of the alternatives given. The exactness score is reflected
+      in some rank features, such that it is possible to rank more exact matches over less exact ones.
+      Use 1.0 as the exactness of all alternatives if exactness information is not available or appropriate.
     </p>
-    <ul>
-      <li>
-        Semantically it means: <em>match any of these alternatives, but treat some as more "exact" than others.</em>
-      </li>
-      <li>
-        It has no effect on whether a document matches,
-        all alternatives are equally valid for retrieval (they're combined via an OR/equiv construct).
-      </li>
-      <li>
-        It only affects ranking: the exactness value flows into <em>TermFieldMatchDataPosition::setMatchExactness()</em>
-        and feeds rank features like fieldMatch(field).exactness, <!-- ToDo: There is no exactness at en/reference/ranking/rank-features.html - fix this and add link -->
-        so a match via a high-exactness alternative scores better than a match via a low-exactness one.
-      </li>
-    </ul>
     <p>
-      Typical use case: query rewriting/stemming,
-      where you search for both the literal user term and a stemmed/synonym form,
-      but want the literal form to rank higher.
-      E.g. <code>alternatives({"sneakers":1.0, "shoes":0.7})</code>‚ either matches,
-      but a document matching "sneakers" literally ranks above one that only matched via the stem "shoes".
+      Prefer <code>alternatives</code> to equiv when the purpose is to express alternative forms of a single token.
     </p>
-  </td>
   </tr>
 <!-- ToDo: for later, link to some resource explaining where to use equiv and alternatives -->