Add doc tweaks while we're at it

x-pack/plugins/inference/server/tasks/nl_to_esql/esql_docs/esql-bucket.txt

@@ -4,7 +4,7 @@ The BUCKET function allows you to create groups of values, known as buckets, fro
 
 ## Syntax
 
-`BUCKET(field, buckets, from, to)`
+`BUCKET(field, buckets [, from, to])`
 
 ### Parameters
 
@@ -18,15 +18,24 @@ The target number of buckets, or the desired bucket size if `from` and `to` para
 
 #### from
 
-The start of the range. This can be a number, a date, or a date expressed as a string.
+(optional) The start of the range. This can be a number, a date, or a date expressed as a string.
 
 #### to
 
-The end of the range. This can be a number, a date, or a date expressed as a string.
+(optional) The end of the range. This can be a number, a date, or a date expressed as a string.
 
-## Examples
+## Important notes:
+
+BUCKET can operate in two modes:
+- one where the bucket size is computed based on a bucket count recommendation and a range,
+- and another where the bucket size is provided directly.
 
-BUCKET can operate in two modes: one where the bucket size is computed based on a bucket count recommendation and a range, and another where the bucket size is provided directly.
+When the bucket size is provided directly for time interval,
+it is expressed as a *timespan literal*, e.g.
+- GOOD: `BUCKET(@timestamp, 1 month)`
+- BAD: `BUCKET(@timestamp, "month")`
+
+## Examples
 
 For instance, asking for at most 20 buckets over a year results in monthly buckets:
 

x-pack/plugins/inference/server/tasks/nl_to_esql/esql_docs/esql-date_trunc.txt

@@ -16,6 +16,14 @@ This is the interval to which the date will be rounded down. It is expressed usi
 
 This is the date expression that will be rounded down.
 
+## Important notes
+
+The *interval* parameter of DATE_TRUNC is a timespan literal, NOT a string.
+  - GOOD: `DATE_TRUNC(1 year, date)`
+  - BAD: `DATE_TRUNC("year", date)`
+
+When grouping data by time interval, it is recommended to use BUCKET instead of DATE_TRUNC.
+
 ## Examples
 
 The following example rounds down the hire_date to the nearest year:

x-pack/plugins/inference/server/tasks/nl_to_esql/esql_docs/esql-syntax.txt

@@ -43,7 +43,7 @@ FROM index
 
 ## Literals
 
-ES|QL currently supports numeric and string literals.
+ES|QL currently supports numeric, string and timespan literals.
 
 ### String Literals
 
@@ -93,11 +93,11 @@ These qualifiers are supported:
 - `quarter`/`quarters`/`q`
 - `year`/`years`/`yr`/`y`
 
-Timespan literals are not whitespace sensitive. These expressions are all valid:
-
-- 1day
-- 1 day
-- 1       day
+Timespan literals are not whitespace sensitive, and should not be wrapped with quotes:
+- GOOD: 1day
+- GOOD: 1 day
+- BAD: "day"
+- BAD: "2 days"
 
 ## Example Queries with Timespan Literals
 
@@ -137,6 +137,15 @@ FROM sales
 | SORT week
 ```
 
+4. The same example with BUCKET instead of DATE_TRUNC:
+
+```esql
+FROM sales
+| WHERE @timestamp > NOW() - 1 quarter
+| STATS weekly_sales = SUM(sales_amount) BY week = BUCKET(@timestamp, 1 week)
+| SORT week
+```
+
 5. Retrieve error logs from the last 15 minutes and group by error type:
 
 ```esql