Incremental sort docs and release announcement

Greetings,

* James Coleman (jtc331@gmail.com) wrote:

I'm breaking out a few questions I'd posed on another thread about the
release timeline [1] into this new thread.

I noticed on the PG13 release announcement that the link for
incremental sort goes to the GUC docs [2] because (as Jonathan Katz
confirmed in the linked thread) that page actually has helpful anchor
tags.

But I'm wondering if instead/also it should point to the examples in
the EXPLAIN docs [3] which actually explain what incremental sort
does. In the initial patch discussion we ended up putting the
explanation there because there was a desire to keep the GUC
descriptions short.

I agree that it would be quite nice to have that.

But that raises a larger question: should the GUC page also link to
the EXPLAIN examples? There's not an obvious anchor tag on the page
(that I can tell) to use for such a link though...so that could get
into an ever larger question about adding those anchors.

Yes, it'd be useful to have the GUCs cross-reference into the places in
the docs that explain the things those GUCs control in more detail,
which I agree means adding more anchors.. I wonder if we could do so in
some way where we put in anchors that are basically "hey, this GUC
impacts this feature" and automagically build the links ...

It seems to me that we don't have a particularly great place for
detail explanations in the docs of the algorithms/nodes/etc. we
use...unless the new glossary section in the docs could fill that
role?

I agree that it's a bit unfortunate that we don't have that and would
like to see that changed, though that would mean we'd have that much
more documentation to maintain.. I'm not sure that's a bad thing but
it's a trade-off we need to consider.

Thanks,

Stephen