public inbox for [email protected]
help / color / mirror / Atom feedFrom: Chao Li <[email protected]>
To: Dragos Andriciuc <[email protected]>
Cc: David G. Johnston <[email protected]>
Cc: Philip Alger <[email protected]>
Cc: Andreas Karlsson <[email protected]>
Cc: [email protected] <[email protected]>
Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
Date: Thu, 26 Feb 2026 16:48:25 +0800
Message-ID: <[email protected]> (raw)
In-Reply-To: <LO7P302MB2254B600583EC8938F7931D3F86BA@LO7P302MB2254.GBRP302.PROD.OUTLOOK.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>
<CAKFQuwZjMOKiLXUFPFLvxLRBzd=GLV6HXPzn4brsFbvHAQzufg@mail.gmail.com>
<LO7P302MB2254B600583EC8938F7931D3F86BA@LO7P302MB2254.GBRP302.PROD.OUTLOOK.COM>
> On Feb 20, 2026, at 01:04, Dragos Andriciuc <[email protected]> wrote:
>
> Hello,
>
> The chapter currently opens directly with a list of subsections and no introductory text.
>
> This differs from the structure used in other chapters, but I understand the preference for avoiding redundancy with the ToC.
>
> I've revised the introduction to simplify the structure and avoid restating the table of contents too directly, merging the two sentences into one.
>
> Attached is v3.
>
>
>
> From: David G. Johnston <[email protected]>
> Sent: Thursday, February 19, 2026 6:14 PM
> To: Philip Alger <[email protected]>
> Cc: Dragos Andriciuc <[email protected]>; Andreas Karlsson <[email protected]>; [email protected] <[email protected]>
> Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
> 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.
>
>
> <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/
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], [email protected]
Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
In-Reply-To: <[email protected]>
* 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