Really hard to find the APIs you are looking for in anomaly detection section

[sophiec20]

https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-ml-anomaly

It's very difficult to find the APIs you need

1. The list is long and full of repeated items (see Unique summaries per path elasticsearch-specification#4277 )
2. The description is longer text and therefore harder to scan. e.g. Delete forecast has become Delete forecast from a job and Get records has become Get anomaly records for an anomaly detection job
3. The ordering has changed.. but I can't tell how its meant to be ordered. Before it was alphabetical (add, create, delete, get, update). Now its all over the place. Its sometimes alphabetical. And sometimes grouped (although the groups are not always applied propery).
4. The most common APIs (Get jobs, Create jobs) are almost impossible to pick out

cc @valeriy42

[pquentin]

I transferred this issue from the Elasticsearch specification repository, as this is where all docs issues are recorded.

[timto-elastic]

@sophiec20 on #3-4, should the list be alphabetical or curated by most common APIs? I've been having a discussion with folks on how to address #1 this week. Looking into #2 (summary is being used for different things).

[timto-elastic]

@swallez for #3, how does the order of operations get determined in the JSON spec file? Bump just generates based on that order. How can we change the ordereing? Does that need to be in the TS somehow?

[swallez]

@timto-elastic the order is the alphabetical order of endpoint identifiers, as can be seen in this directory.

I don't think we have any other information available right now that would allow defining another stable order. We should consider adding files similar (or even identical) to the doc system's toc.yml to the API spec where we can manually define the ordering, and that both endpoints and namespaces in way that makes more sense to humans.

[timto-elastic]

thanks @swallez. I like the toc.yml idea. I think there are definitely things we can do to structure the nav better. It would be great if there were a way to control that.