Merge pull request prometheus#16009 from charleskorn/topk-bottomk-sorting

docs: make sorting behaviour of `topk` and `bottomk` explicit

Author: beorn7

docs/querying/operators.md

@@ -319,7 +319,14 @@ the input samples, including the original labels, are returned in the result
 vector. `by` and `without` are only used to bucket the input vector. Similar to
 `min` and `max`, they only operate on float samples, considering `NaN` values
 to be farthest from the top or bottom, respectively. Histogram samples in the
-input vector are ignored, flagged by an info-level annotation.
+input vector are ignored, flagged by an info-level annotation. 
+
+If used in an instant query, `topk` and `bottomk` return series ordered by
+value in descending or ascending order, respectively. If used with `by` or
+`without`, then series within each bucket are sorted by value, and series in
+the same bucket are returned consecutively, but there is no guarantee that
+buckets of series will be returned in any particular order. No sorting applies
+to range queries.
 
 `limitk` and `limit_ratio` also return a subset of the input samples, including
 the original labels in the result vector. The subset is selected in a
@@ -334,7 +341,7 @@ the input samples, while `limit_ratio(-0.9, ...)` returns precisely the
 remaining approximately 90% of the input samples not returned by
 `limit_ratio(0.1, ...)`.
 
-`group` and `count` do not do not interact with the sample values,
+`group` and `count` do not interact with the sample values,
 they work in the same way for float samples and histogram samples.
 
 `count_values` outputs one time series per unique sample value. Each series has