A few suggestions for this page.
First, move the “Plugs and slots” section to the beginning, as it is the basis for the entire rest of the page; it makes no sense for it to be partway down the page.
Next, the two sections “Listing interfaces” and “Listing connections” document exactly the same commands: “snap connections” and “snap connections --all”, so it makes little sense to break that over two distinct sections, just cover that command all at once and show its variations.
On the other hand, in the “Plugs and slots” section, there is a passing reference to the “snap interface” command; that deserves its own section. Effectively, I envision two sections:
Investigating connections (“snap connections”) Investigating interfaces (“snap interface”)
or something like that, that seems to flow more smoothly.
Next, for “snap interface”, you should cover the “–all” and “–attrs” options, which raises the question – where are interface attributes documented? That’s why this command merits its own section; there are things to say about it.
Next, in the section “Disconnect interfaces”, I think you really need to emphasize the “–forget” option to disconnect. (Also, where is this information stored so it can be re-consulted? I assume snapd, but just want to confirm.)
Finally, there is no mention of “greedy” plugs, as documented here: Plug/slot declaration rules: greedy plugs. Should there be at least a reference or link to that page? And as I recall, the concept of greedy plugs is referred to as “arity”, but I don’t see that word being used a lot. Should that be the official descriptor of this concept?