Content-Type: text/plain;
	charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.400.21\))
Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
From: Chao Li <li.evan.chao@gmail.com>
In-Reply-To: <LO7P302MB2254B600583EC8938F7931D3F86BA@LO7P302MB2254.GBRP302.PROD.OUTLOOK.COM>
Date: Thu, 26 Feb 2026 16:48:25 +0800
Cc: "David G. Johnston" <david.g.johnston@gmail.com>,
 Philip Alger <paalger0@gmail.com>,
 Andreas Karlsson <andreas@proxel.se>,
 "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Content-Transfer-Encoding: quoted-printable
Message-Id: <A1BE98AA-0147-48CC-A5BC-23916B277BEA@gmail.com>
References: <LO7P302MB2254ED63D99DEC176E8C50FEF86DA@LO7P302MB2254.GBRP302.PROD.OUTLOOK.COM>
 <0bd69007-f591-4584-aa13-037be2171aea@proxel.se>
 <CAM-ipWdfB3npDkT+xZbtBz_qAbewFE784BdY1a2zRUGmC1xPwA@mail.gmail.com>
 <CAPXBC8K0j-=zymexP+nxFAzKuDd9cz5HUi_sC4xvuPwJGAUB_w@mail.gmail.com>
 <CAKFQuwZjMOKiLXUFPFLvxLRBzd=GLV6HXPzn4brsFbvHAQzufg@mail.gmail.com>
 <LO7P302MB2254B600583EC8938F7931D3F86BA@LO7P302MB2254.GBRP302.PROD.OUTLOOK.COM>
To: Dragos Andriciuc <dragos.andriciuc@percona.com>
Archived-At: <https://www.postgresql.org/message-id/A1BE98AA-0147-48CC-A5BC-23916B277BEA%40gmail.com>
Precedence: bulk


> On Feb 20, 2026, at 01:04, Dragos Andriciuc =
<dragos.andriciuc@percona.com> wrote:
>=20
> Hello,
>=20
> The chapter currently opens directly with a list of subsections and no =
introductory text.
>=20
> This differs from the structure used in other chapters, but I =
understand the preference for avoiding redundancy with the ToC.
>=20
> I've revised the introduction to simplify the structure and avoid =
restating the table of contents too directly, merging the two sentences =
into one.
>=20
> Attached is v3.
>=20
>=20
>=20
> From: David G. Johnston <david.g.johnston@gmail.com>
> Sent: Thursday, February 19, 2026 6:14 PM
> To: Philip Alger <paalger0@gmail.com>
> Cc: Dragos Andriciuc <dragos.andriciuc@percona.com>; Andreas Karlsson =
<andreas@proxel.se>; pgsql-hackers@postgresql.org =
<pgsql-hackers@postgresql.org>
> Subject: Re: DOCS - Add introductory paragraph to Getting Started =
chapter
>  On Thu, Feb 19, 2026 at 6:51=E2=80=AFAM Philip Alger =
<paalger0@gmail.com> wrote:
>=20
>=20
> On Thu, Feb 19, 2026 at 3:58=E2=80=AFAM Dragos Andriciuc =
<dragos.andriciuc@percona.com> wrote:
> Thanks for pointing that out. The intention was to add two paragraphs =
and it is now corrected to use
> two separate <para> tags. Attached is v2 of the patch.
>=20
> I have verified that the docs build and render correctly in HTML =
locally.
>=20
>=20
> Hello,
>=20
> It's always good to add more documentation. I wouldn't consider two =
single sentences as separate paragraphs though.=20
>=20
> However, I think these sentences can be combined into one.
>=20
> For example:
>=20
> This chapter provides a practical introduction to =
<productname>PostgreSQL</productname>
> by guiding you through software installation, basic architectural =
concepts, and how to create and access=20
> your first database.
>=20
> I think this version combines the two essentially.
>=20
>  All that does is put the existing Table of Contents into paragraph =
form.  I'd keep the second sentence and let the ToC speak for itself =
personally.  Or put a bit more effort into saying something about those =
topics that a ToC header cannot convey.  I'm fine with the status quo =
though, at least compared to the proposed.
>=20
> Probably should make 'server', 'client' and 'database' links to the =
glossary - though the architecture page will also provide detail if they =
perform a linear read.
>=20
> Looking at this more critically, why does installation come before =
architecture?  I would expect architecture to include information that =
improves understanding what is being installed and why.  Or, more =
generally, theory before practice.
>=20
> Suggestion:
> <para>
> [First] This chapter provides a brief introduction to the concepts and =
terminology employed in PostgreSQL's design.  [Then] It also walks you =
through getting a server and client installed on your machine and =
ensuring it is functioning by creating a new database and connecting to =
it via the command line client.
> </para>
>=20
> David J.
>=20
>=20
> <v3-0001-Add-introductory-paragraph-to-Getting-Started-chapter.patch>

V3 seems very polished. I agree the new paragraph is a helpful =
improvement for new doc readers.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/