Обсуждение: DOCS - Add introductory paragraph to Getting Started chapter

On 2/18/26 10:28 AM, Dragos Andriciuc wrote:
> The "Getting Started" chapter currently lacks an introductory paragraph 
> explaining its scope.
> 
> This patch adds a brief introduction describing the topics covered in 
> the chapter.
> 
> Patch attached.

I have not looked at the actual contents of the change but did you 
intend to add one or two paragraphs? You intent is a bit unclear since 
you have added a double newline within a <para> tag. If you intended two 
paragraphs it should be two <para> tags and if not there shouldn't be a 
double newline.

Have you set it up so you can render the documentation to HTML locally?

Andreas

> On Feb 20, 2026, at 01:04, Dragos Andriciuc <dragos.andriciuc@percona.com> 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
theToC. 
>
> I've revised the introduction to simplify the structure and avoid restating the table of contents too directly,
mergingthe two sentences into one. 
>
> Attached is v3.
>
>
>
> 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 AM Philip Alger <paalger0@gmail.com> wrote:
>
>
> On Thu, Feb 19, 2026 at 3:58 AM 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.
>
> 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
ToCspeak for itself personally.  Or put a bit more effort into saying something about those topics that a ToC header
cannotconvey.  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
providedetail if they perform a linear read. 
>
> Looking at this more critically, why does installation come before architecture?  I would expect architecture to
includeinformation 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
creatinga 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/

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Thu, Feb 26, 2026 at 1:49 AM Chao Li <li.evan.chao@gmail.com> wrote:
>>> <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.

> Works for me.

I have no particular objection to this patch, but I wonder why it
only addresses the tutorial's Chapter 1.  Chapters 2 and 3 likewise
lack any introductory paragraph.

            regards, tom lane

On 4/8/26 3:05 AM, Dapeng Wang wrote:
> Following up on Tom's suggestion that Chapters 2 and 3 of the
> tutorial likewise lack introductory paragraphs, I've attached a
> patch that adds them.
Thanks for the contribution!

In the future use "Reply all" and figure out why your email client did 
not add a proper Reply-To header.

-- 
Andreas Karlsson
Percona

On 4/10/26 2:36 AM, Dapeng Wang wrote:
> Thanks Andreas! Noted - I didn't have the original thread
> in my mailbox at the time, but I'm subscribed now so future
> replies will thread properly.

I see! Then the general recommendation is to use the re-send email 
button in our mailing list archives. I know it was buggy some time ago 
but I think it has been fixed now.

Andreas

Andreas Karlsson <andreas@proxel.se> writes:
> On 4/10/26 2:36 AM, Dapeng Wang wrote:
>> Thanks Andreas! Noted - I didn't have the original thread
>> in my mailbox at the time, but I'm subscribed now so future
>> replies will thread properly.

> I see! Then the general recommendation is to use the re-send email 
> button in our mailing list archives. I know it was buggy some time ago 
> but I think it has been fixed now.

Yeah, I use that all the time when I want to reply to some old
thread that I no longer have locally.  It's been flaky once or
twice for me, but normally it works fine.

A more pressing problem is that this iteration of the thread
isn't attached to the CF entry; you need to do that so that
it shows up as having current traffic.  Right now,

https://commitfest.postgresql.org/patch/6506/

still shows the 19-Feb patch as current.

            regards, tom lane

On 08.04.26 03:05, Dapeng Wang wrote:
> Following up on Tom's suggestion that Chapters 2 and 3 of the
> tutorial likewise lack introductory paragraphs, I've attached a
> patch that adds them.

In each of these chapters, the first section is titled "Introduction" 
and the first sentence introduces the chapter.  So the text you are 
proposing to add here appears to be redundant with that.