Improve 'alternatives' doc

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 <a href="../ranking/rank-features.html#fieldTermMatch(name,n).exactness">fieldMatch(field).exactness</a>,
-        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 -->