Content-Type: text/plain;
	charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3776.700.51.11.1\))
Subject: Re: Moving the vacuum GUCs' docs out of the Client Connection
 Defaults section
From: Daniel Gustafsson <daniel@yesql.se>
In-Reply-To: 
 <CAAKRu_ZR8aqiZ0SHK8Rqd7QVAmr6XX9Xpkie9vmZAkyb69YOiQ@mail.gmail.com>
Date: Thu, 9 Jan 2025 23:05:46 +0100
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-Transfer-Encoding: quoted-printable
Message-Id: <ED2C0322-DA08-4B60-8A08-C69128182C68@yesql.se>
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>
To: Melanie Plageman <melanieplageman@gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/ED2C0322-DA08-4B60-8A08-C69128182C68%40yesql.se>
Precedence: bulk

> On 9 Jan 2025, at 02:45, Melanie Plageman <melanieplageman@gmail.com> =
wrote:

> Attached is v2 (required a rebase).

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=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 =
this
subsection with a sentence describing what freezing actually is.  Vacuum =
is
hard enough for users as it is =3D)


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


+      <varname>vacuum_cost_delay</varname>. Then it will reset the =
counter and
+      continue execution.
I know starting a sentence with "Then" is grammatically correct when =
it's the
last sentence in a paragraph, but being a non-native speaker I always =
find
myself re-reading such sentences to parse them as they stand out as odd.


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

--
Daniel Gustafsson