public inbox for [email protected]  

help / color / mirror / Atom feed

From: David G. Johnston <[email protected]>
To: Philip Alger <[email protected]>
Cc: Dragos Andriciuc <[email protected]>
Cc: Andreas Karlsson <[email protected]>
Cc: [email protected] <[email protected]>
Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
Date: Thu, 19 Feb 2026 09:14:45 -0700
Message-ID: <CAKFQuwZjMOKiLXUFPFLvxLRBzd=GLV6HXPzn4brsFbvHAQzufg@mail.gmail.com> (raw)
In-Reply-To: <CAPXBC8K0j-=zymexP+nxFAzKuDd9cz5HUi_sC4xvuPwJGAUB_w@mail.gmail.com>
References: <LO7P302MB2254ED63D99DEC176E8C50FEF86DA@LO7P302MB2254.GBRP302.PROD.OUTLOOK.COM>
	<[email protected]>
	<CAM-ipWdfB3npDkT+xZbtBz_qAbewFE784BdY1a2zRUGmC1xPwA@mail.gmail.com>
	<CAPXBC8K0j-=zymexP+nxFAzKuDd9cz5HUi_sC4xvuPwJGAUB_w@mail.gmail.com>

On Thu, Feb 19, 2026 at 6:51 AM Philip Alger <[email protected]> wrote:

>
>
> On Thu, Feb 19, 2026 at 3:58 AM Dragos Andriciuc <
> [email protected]> 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.
>>
>> 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 single
> 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.

view thread (5+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected]
  Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
  In-Reply-To: <CAKFQuwZjMOKiLXUFPFLvxLRBzd=GLV6HXPzn4brsFbvHAQzufg@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox