Обсуждение: 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