Re: Incremental sort docs and release announcement

Greetings,

* James Coleman (jtc331(at)gmail(dot)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