I was unaware of the existence of a docs mailing list. I'll post this there.
On 2019-10-19 17:07, Jeff Janes wrote:
The following bug has been logged on the website:
Bug reference: 16065
Logged by: Eric Toombs
Email address: ewtoombs@uwaterloo.ca
PostgreSQL version: 12.0
Operating system: any
Description:
The official documentation of EXPLAIN is here:
https://www.postgresql.org/docs/current/sql-explain.html
It's a start, but it doesn't actually define any of the operation nodes in
the query plan tree it outputs, e.g. Seq Scan, Index Scan, Index Only Scan,
HashAggregate, Nested Loop, Nested Loop Semi Join, Nested Loop Anti Join,
etc.. Online, there are descriptions (i.e. guesses) of what each operation
node is actually doing, but these descriptions are not authoritative.
I agree that the documentation of EXPLAIN is sparse in general, but I don't buy this particular complaint. If someone doesn't know what a Nested Loop is, are they going to understand any reasonable length description of it which we can offer? If someone doesn't know the very basic vocabulary of computer operations, what words could we use to explain things to them?
There may be value in providing translations of those terms into other languages, but that is a different topic.
With authoritative definitions of each operation node, there would be no
more guesswork, and DBAs could have a much more reliable mental model of
what a query plan actually does.
It seems like an infinite regress where we have to provide an authoritative definition of every word we use while providing the authoritative definitions of the other words we use. Maybe some clever person can break that loop, but without seeing a concrete proposal I am skeptical it can be done.
In any event, it certainly isn't a bug. Probably the docs mailing list would be a better venue to discuss it.
Cheers,
Jeff