Re: Moving the vacuum GUCs' docs out of the Client Connection Defaults section

> On 10 Jan 2025, at 23:09, Melanie Plageman <melanieplageman(at)gmail(dot)com> wrote:
>
> On Thu, Jan 9, 2025 at 5:05 PM Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:
>>
>> I think this is a really good restructuring which will make life easier for our
>> users. Some of the comments below are on wording which wasn't introduced in
>> this patch, but which I hadn't thought about before, so feel free to ignore
>> those comments.
>>
>> + <sect2 id="runtime-config-vacuum-freezing">
>> + <title>Freezing</title>
>> +
>> + <para>
>> Trying to read this as a new user, I think it would be good to start this
>> subsection with a sentence describing what freezing actually is. Vacuum is
>> hard enough for users as it is =)
>
> I've taken a stab at improving this. Let me know if you think it works.

I like what you added, it's IMO the right level of detail here.

>> + default value is one.
>> Grepping around indicates that we typically use the numeric value rather than
>> writing it in text, and the next settting down has "default value is 2". For
>> consistency I would change that to "1" instead of "one".
>
> I think this is a reasonable cleanup to lump in with the rest of this
> commit. I have taken the liberty of also adding a <literal> tag and
> then updating the other places in the proposed "Vacuuming" subsection
> where a literal default value is specified without the <literal> tag.

LGTM. We're not entirely consistent with how we mark up the default value, but
I think moving towards using <literal>value</literal> whenever we are changing
things there anyways is the right level of cleanup.

>> + can be set to fractional-millisecond values, such delays may not be
>> + measured accurately on older platforms. On such platforms,
>> This sentence seems quite vague and hard to act on for users, what qualifies as
>> an "older platform" by the time v18 rolls around (this was added in v12). I'm
>> sure there are such platforms in existence that postgres 18 will run on, but
>> are we helping users with ambiguity?
>
> While I agree that what counted as older hardware in 2019 may no
> longer be around at all, I am more hesitant to update this in the same
> commit as a bunch of other cut-and-pastes. Someone at some point
> decided this was important to point out, and I don't have sufficient
> evidence that it no longer makes sense. And if I did, I'd probably
> want to update this part of the docs in a dedicated commit.

To be fair I didn't really expect this to be changed as part of this (and I
should written that in my email), but it stood out when reading so wanted to
point it out. No objections to leaving it as is as part of this work.

+ Specifies the cutoff age (in multixacts) that <command>VACUUM</command>
I wish we had a glossary entry for multixact we could link to here. But,
that's not really the responsibility of this patch to fix, just something that
came to mind when reading the resulting page.

+1 on going ahead with this version, there are still improvements we can make
to the vacuum config docs but that shouldn't stand in the way of a reorg patch
which improves overall presentation structure.

--
Daniel Gustafsson