Improving API Docs

[xavierleune]

Following the discussion on the issue #5961 with @mkeeler I'm opening this issue to discuss about the best way to improve the documentation on the filtering api, specially the magic argument to filter healthy nodes from the list of services.

First, please let me give you some context, maybe it'll be useful to understand why I'm doing those suggestions - or to understand why some of them are stupids ^^^
Even if I'm pretty involved in architecture / infrastructure technical decisions, I'm not an ops guy. Consul have been chosen and installed by the ops team, I'm using it as a developer who needs to retrieve a list of nodes running some services (and up). So I'm only using the API and keep focused on that.
I've been a little bit lost on the consul documentation, probably because I'm not an ops guy and the menu of the API documentation mixes different kind of APIs. All the API's are at the same level - this makes sense because they are separated, but actually they can be grouped, perhaps like this

• Management related API's: ACL / Config / Connect / Snapshot / Status
• Catalog & services related API's: Catalog / Coordinate / Health / Session
• Other features related API's: KV / ...
• General features of the API's: Filtering / Transactions

Being a developer trying to focus on using consul and not managing it can be hard. I don't know Consul from the inside. Looking at the menu and knowing what item is referring to what kind of API is not obvious. All API's are very well documented and the documentation is very clear, but I think that there is room for improving the menu.
You may say that this is not related to #5961 but actually it can be. Improving the menu will lead to have a better exposure for the filtering API and to show the connexions between API's. Catalog and health are separated apis but they are both working around services.

By creating a new level on the API documentation with a landing page for each item, it would be easier to introduce the "?passing" magic argument, by creating some internal links between related API's.

TL;DR:

• I suggest to group the API's by theme
• I suggest to add an introduction page to each API's group, introducing what this groups focuses on and how subitems are related to each other
• Thank you for the quality of the documentation, which is already great

WDYT ?