Re: DOCS - Add introductory paragraph to Getting Started chapter

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 <david(dot)g(dot)johnston(at)gmail(dot)com>
Sent: Thursday, February 19, 2026 6:14 PM
To: Philip Alger <paalger0(at)gmail(dot)com>
Cc: Dragos Andriciuc <dragos(dot)andriciuc(at)percona(dot)com>; Andreas Karlsson <andreas(at)proxel(dot)se>; pgsql-hackers(at)postgresql(dot)org <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter

On Thu, Feb 19, 2026 at 6:51 AM Philip Alger <paalger0(at)gmail(dot)com<mailto:paalger0(at)gmail(dot)com>> wrote:

On Thu, Feb 19, 2026 at 3:58 AM Dragos Andriciuc <dragos(dot)andriciuc(at)percona(dot)com<mailto:dragos(dot)andriciuc(at)percona(dot)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 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.