diff --git a/core/modules/search/src/SearchQuery.php b/core/modules/search/src/SearchQuery.php
index c1ecb48494ca16fdd06678d03dfc74e23cd0b117..375ca2ab44287cb15da790601f3e688772de3c15 100644
--- a/core/modules/search/src/SearchQuery.php
+++ b/core/modules/search/src/SearchQuery.php
@@ -486,10 +486,10 @@ public function preExecute(SelectInterface $query = NULL) {
    * used. However, if at least one call to addScore() has taken place, the
    * keyword relevance score is not automatically added.
    *
-   * Also note that if you call orderBy() directly on the query, search scores
-   * will not automatically be used to order search results. Your orderBy()
-   * expression can reference 'calculated_score', which will be the total
-   * calculated score value.
+   * Note that you must use this method to add ordering to your searches, and
+   * not call orderBy() directly, when using the SearchQuery extender. This is
+   * because of the two-pass system the SearchQuery class uses to normalize
+   * scores.
    *
    * @param string $score
    *   The score expression, which should evaluate to a number between 0 and 1.