Common options docs includes docs for options that are not common to all APIs

[DaveCTurner]

The common options docs describes the truly common options:

• ?pretty
• ?human
• ?filter_path
• ?error_trace

However it also has some docs about date math which I think would more accurately be described as an API convention, some docs on fuzziness that only apply to search APIs so should be in those APIs docs alone, and the ?flat_settings option which only applies to a few specific APIs too (primarily the ones that reference org.elasticsearch.common.settings.Settings#FORMAT_PARAMS).

Could we rework this area so that the common options page only mentions the truly common options?

[elasticsearchmachine]

Pinging @elastic/es-docs (Team:Docs)

[elasticsearchmachine]

Pinging @elastic/es-core-infra (Team:Core/Infra)

[lcawl]

It's worth noting that this page will likely be retired as we migrate over to the new site (https://www.elastic.co/docs/api/doc/elasticsearch) so if this page is still required, it ought to be re-written as part of the introductory text in the OpenAPI document. In the Kibana API docs, we've added some new pages as x-topics, so the same could be accomplished in one of the overlays, e.g. https://github.com/elastic/elasticsearch-specification/blob/main/docs/overlays/elasticsearch-shared-overlays.yaml

[DaveCTurner]

Thanks @lcawl, yes that makes sense. Since we're moving to docs generated from the specification, could we add these common options to every individual endpoint's docs too? Although it's useful to know that these options are automatically available on every endpoint, it's also quite hard to discover that if you're only thinking about a single endpoint.

[lcawl]

... could we add these common options to every individual endpoint's docs too?

I believe that's the type of info discussed in https://github.com/elastic/elasticsearch-specification/blob/main/docs/behaviors.md#commonqueryparameters and if not it should be something the devtools folks know how to encode.