[DOCS] Reformat avg bucket agg reference #69751
Conversation
jrodewig
added
>docs
elasticmachine
added
Team:Analytics
|
Pinging @elastic/es-analytics-geo (Team:Analytics) |
|
Pinging @elastic/es-docs (Team:Docs) |
| } | ||
| } | ||
| -------------------------------------------------- | ||
| ---- | ||
| // NOTCONSOLE |
There was a problem hiding this comment.
I think its probably helpful to spend the extra lines to turn this into a CONSOLE example. We'll get the test from it and readers will know where the agg sits in the request tree.
There was a problem hiding this comment.
Looking again, it really is a lot of lines. And we already say we'll have an example below. So I'm not really sure. I do like full examples, but this one would take up the whole screen......
There was a problem hiding this comment.
Thanks for the feedback @nik9000. I considered either converting this to a full example OR simply moving the example below up. However, it can be difficult to spot where exactly the avg_bucket agg begins/ends. We can do callouts, but that requires a bit more parsing on the part of the reader. I imagine that'll be a problem for most of our pipeline aggs.
There was a problem hiding this comment.
It is like you say, yikes. Do you think we could have the syntax block include a tagged region from the example below? That way at least it won't drift.
There was a problem hiding this comment.
That's a great idea! I implemented this with 105e3b1 (and some cleanup with ee06c0d).
The tagged region comments are now visible in the example. I don't think there is a substitution combo that lets you get rid of them. However, I don't think that's necessarily a bad thing. It does a good job of calling out the agg configuration in context.
There was a problem hiding this comment.
Is it worth adding callouts for the tagged regions? Just something to explain to the users that the tags indicate the agg configuration but aren't actually part of the example.
Reformats reference documentation for the average bucket aggregation.
I plan to use these docs as a template for other agg reference documentation.
Relates to #69215, #66208, #66205, #53304
Preview
https://elasticsearch_69751.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/search-aggregations-pipeline-avg-bucket-aggregation.html