MIME-Version: 1.0
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>
In-Reply-To: <CAPXBC8K0j-=zymexP+nxFAzKuDd9cz5HUi_sC4xvuPwJGAUB_w@mail.gmail.com>
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Thu, 19 Feb 2026 09:14:45 -0700
Message-ID: <CAKFQuwZjMOKiLXUFPFLvxLRBzd=GLV6HXPzn4brsFbvHAQzufg@mail.gmail.com>
Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
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>
Content-Type: multipart/alternative; boundary="00000000000080fb07064b2f9cc9"
Archived-At: <https://www.postgresql.org/message-id/CAKFQuwZjMOKiLXUFPFLvxLRBzd%3DGLV6HXPzn4brsFbvHAQzufg%40mail.gmail.com>
Precedence: bulk

--00000000000080fb07064b2f9cc9
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Thu, Feb 19, 2026 at 6:51=E2=80=AFAM Philip Alger <paalger0@gmail.com> w=
rote:

>
>
> 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 an=
d
>> it is now corrected to use
>> two separate <para> tags. Attached is v2 of the patch.
>>
>> I have verified that the docs build and render correctly in HTML locally=
.
>>
>>>
>>>
> Hello,
>
> It's always good to add more documentation. I wouldn't consider two singl=
e
> sentences as separate paragraphs though.
>
> However, I think these sentences can be combined into one.
>
> For example:
>
> 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
> your first database.
>
> I think this version combines the two essentially.
>
>
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.

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.

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.

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>

David J.

--00000000000080fb07064b2f9cc9
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><div class=3D"gmail_default" style=3D"fon=
t-family:arial,helvetica,sans-serif"><span style=3D"font-family:Arial,Helve=
tica,sans-serif">On Thu, Feb 19, 2026 at 6:51=E2=80=AFAM Philip Alger &lt;<=
a href=3D"mailto:paalger0@gmail.com">paalger0@gmail.com</a>&gt; wrote:</spa=
n></div></div><div class=3D"gmail_quote gmail_quote_container"><blockquote =
class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px sol=
id rgb(204,204,204);padding-left:1ex"><div dir=3D"ltr"><div dir=3D"ltr"><br=
></div><br><div class=3D"gmail_quote"><div dir=3D"ltr" class=3D"gmail_attr"=
>On Thu, Feb 19, 2026 at 3:58=E2=80=AFAM Dragos Andriciuc &lt;<a href=3D"ma=
ilto:dragos.andriciuc@percona.com" target=3D"_blank">dragos.andriciuc@perco=
na.com</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" style=3D"m=
argin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left=
:1ex"><div dir=3D"ltr"><div dir=3D"ltr">Thanks for pointing that out. The i=
ntention was to add two paragraphs and it is now corrected to use<br>two se=
parate &lt;para&gt; tags. Attached is v2 of the patch.</div><div dir=3D"ltr=
"><br></div><div dir=3D"ltr">I have verified that the docs build and render=
 correctly in HTML locally.<br></div></div><div class=3D"gmail_quote"><bloc=
kquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:=
1px solid rgb(204,204,204);padding-left:1ex"><br></blockquote></div></block=
quote></div><div><br></div><div>Hello,</div><div><br></div><div>It&#39;s al=
ways good to add more documentation. I wouldn&#39;t consider two single sen=
tences as separate paragraphs though.=C2=A0</div><div><br></div><div>Howeve=
r, I think these sentences can be combined into one.</div><div><br></div><d=
iv>For example:</div><div><br></div><div>This chapter=C2=A0provides a pract=
ical introduction to &lt;productname&gt;PostgreSQL&lt;/productname&gt;</div=
><div>by guiding you through software=C2=A0installation, basic architectura=
l concepts, and how to create and access=C2=A0</div><div>your first=C2=A0da=
tabase.</div><div><br></div><div>I think this version combines the two esse=
ntially.</div><div><br></div></div></blockquote><div><span class=3D"gmail_d=
efault" style=3D"font-family:arial,helvetica,sans-serif">=C2=A0</span></div=
><div class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-ser=
if">All that does is put the existing Table of Contents into paragraph form=
.=C2=A0 I&#39;d keep the second sentence and let the ToC speak for itself p=
ersonally.=C2=A0 Or put a bit more effort into saying something about those=
 topics that a ToC header cannot convey.=C2=A0 I&#39;m fine with the status=
 quo though, at least compared to the proposed.</div><div class=3D"gmail_de=
fault" style=3D"font-family:arial,helvetica,sans-serif"><br></div><div clas=
s=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-serif">Probab=
ly should make &#39;server&#39;, &#39;client&#39; and &#39;database&#39; li=
nks to the glossary - though the architecture page will also provide detail=
 if they perform a linear read.</div><div class=3D"gmail_default" style=3D"=
font-family:arial,helvetica,sans-serif"><br></div><div class=3D"gmail_defau=
lt" style=3D"font-family:arial,helvetica,sans-serif">Looking at this more c=
ritically, why does installation come=C2=A0before architecture?=C2=A0 I wou=
ld expect architecture to include information that improves understanding w=
hat is being installed and why.=C2=A0 Or, more generally, theory before pra=
ctice.</div><div class=3D"gmail_default" style=3D"font-family:arial,helveti=
ca,sans-serif"><br></div><div class=3D"gmail_default" style=3D"font-family:=
arial,helvetica,sans-serif"><div class=3D"gmail_default">Suggestion:</div><=
div class=3D"gmail_default">&lt;para&gt;</div><div class=3D"gmail_default">=
[First] This chapter provides a brief introduction to the concepts and term=
inology employed in PostgreSQL&#39;s design.=C2=A0 [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.</div><div class=3D"gmail_default">&lt;/para&gt;</div><=
div class=3D"gmail_default"><br></div></div><div class=3D"gmail_default" st=
yle=3D"font-family:arial,helvetica,sans-serif">David J.</div><div class=3D"=
gmail_default" style=3D"font-family:arial,helvetica,sans-serif"><br></div><=
div class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-serif=
"><br></div></div></div>

--00000000000080fb07064b2f9cc9--