MIME-Version: 1.0
References: 
 <CAAKRu_aQUOaMYrcjNuXeSkJtaX9oRUzKP57bsYbC0gVVWS+cbA@mail.gmail.com>
 <1373018.1736213217@sss.pgh.pa.us>
 <CAAKRu_bz3BD4w0jmjfQkckAQE5eb-Ge2a=9Q-HG_rWSTeG_PzA@mail.gmail.com>
 <CAAKRu_Ymux_RBzp5faSR5-qx1JdM6qS3POVjcWyHbnQjzgmo8g@mail.gmail.com>
 <68a4435c-3990-419d-a68a-b33a7f9185ab@eisentraut.org>
 <CAAKRu_ZR8aqiZ0SHK8Rqd7QVAmr6XX9Xpkie9vmZAkyb69YOiQ@mail.gmail.com>
 <ED2C0322-DA08-4B60-8A08-C69128182C68@yesql.se>
 <CAAKRu_a52vCax5+AN7MstfMckuR1qxyfTmssyPhqZv+9mNiMGQ@mail.gmail.com>
 <77916C10-F124-4652-B842-92508E1696B6@yesql.se>
In-Reply-To: <77916C10-F124-4652-B842-92508E1696B6@yesql.se>
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Fri, 10 Jan 2025 18:31:04 -0500
Message-ID: 
 <CAAKRu_ZochwEBbY7_1n8z_-c5Zvh1EggBkEhYn2i9X4A5LD4ww@mail.gmail.com>
Subject: Re: Moving the vacuum GUCs' docs out of the Client Connection
 Defaults section
To: Daniel Gustafsson <daniel@yesql.se>
Cc: Peter Eisentraut <peter@eisentraut.org>, Tom Lane <tgl@sss.pgh.pa.us>,
	PostgreSQL Hackers <pgsql-hackers@postgresql.org>, "Bossart,
 Nathan" <bossartn@amazon.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/CAAKRu_ZochwEBbY7_1n8z_-c5Zvh1EggBkEhYn2i9X4A5LD4ww%40mail.gmail.com>
Precedence: bulk

On Fri, Jan 10, 2025 at 6:00=E2=80=AFPM Daniel Gustafsson <daniel@yesql.se>=
 wrote:
>
> > On 10 Jan 2025, at 23:09, Melanie Plageman <melanieplageman@gmail.com> =
wrote:
> >
> > On Thu, Jan 9, 2025 at 5:05=E2=80=AFPM Daniel Gustafsson <daniel@yesql.=
se> wrote:
> >>
> >> I think this is a really good restructuring which will make life easie=
r for our
> >> users.  Some of the comments below are on wording which wasn't introdu=
ced in
> >> this patch, but which I hadn't thought about before, so feel free to i=
gnore
> >> those comments.
> >>
> >> +    <sect2 id=3D"runtime-config-vacuum-freezing">
> >> +     <title>Freezing</title>
> >> +
> >> +     <para>
> >> Trying to read this as a new user, I think it would be good to start t=
his
> >> subsection with a sentence describing what freezing actually is.  Vacu=
um is
> >> hard enough for users as it is =3D)
> >
> > 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.

Cool, thanks! I pushed.

> +         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.

Personally, I really wish we had a docs page explaining more about
what mutlixacts are and maybe even a bit about the architecture. FWIW,
the index [1] has an entry for MultiXacts but it goes straight to
MultiXacts and Wraparound [2].

- Melanie

[1] https://www.postgresql.org/docs/devel/bookindex.html
[2] https://www.postgresql.org/docs/devel/routine-vacuuming.html#VACUUM-FOR=
-MULTIXACT-WRAPAROUND