public inbox for [email protected]
help / color / mirror / Atom feedRe: DOCS - Add introductory paragraph to Getting Started chapter
5+ messages / 3 participants
[nested] [flat]
* Re: DOCS - Add introductory paragraph to Getting Started chapter
@ 2026-02-19 16:14 David G. Johnston <[email protected]>
2026-02-19 17:04 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Dragos Andriciuc <[email protected]>
0 siblings, 1 reply; 5+ messages in thread
From: David G. Johnston @ 2026-02-19 16:14 UTC (permalink / raw)
To: Philip Alger <[email protected]>; +Cc: Dragos Andriciuc <[email protected]>; Andreas Karlsson <[email protected]>; pgsql-hackers
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.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: DOCS - Add introductory paragraph to Getting Started chapter
2026-02-19 16:14 Re: DOCS - Add introductory paragraph to Getting Started chapter David G. Johnston <[email protected]>
@ 2026-02-19 17:04 ` Dragos Andriciuc <[email protected]>
2026-02-26 08:48 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Chao Li <[email protected]>
0 siblings, 1 reply; 5+ messages in thread
From: Dragos Andriciuc @ 2026-02-19 17:04 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; Philip Alger <[email protected]>; +Cc: Andreas Karlsson <[email protected]>; pgsql-hackers
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]<mailto:[email protected]>> wrote:
On Thu, Feb 19, 2026 at 3:58 AM Dragos Andriciuc <[email protected]<mailto:[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.
Attachments:
[application/octet-stream] v3-0001-Add-introductory-paragraph-to-Getting-Started-chapter.patch (947B, 3-v3-0001-Add-introductory-paragraph-to-Getting-Started-chapter.patch)
download | inline diff:
From ee4beb3239343a62cba9a49a3a4c5302d256b30c Mon Sep 17 00:00:00 2001
From: Dragos Andriciuc <[email protected]>
Date: Tue, 17 Feb 2026 12:25:03 +0200
Subject: [PATCH] Add introductory paragraph to Getting Started chapter
v3:
- Reword paragraph one to include second paragraph information
---
doc/src/sgml/start.sgml | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 0263a700591..4e28db1b450 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -3,6 +3,12 @@
<chapter id="tutorial-start">
<title>Getting Started</title>
+ <para>
+ This chapter provides a brief introduction to <productname>PostgreSQL</productname>,
+ introducing core concepts and guiding you through installation and the
+ basic steps of creating and accessing a database.
+ </para>
+
<sect1 id="tutorial-install">
<title>Installation</title>
--
2.43.0
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: DOCS - Add introductory paragraph to Getting Started chapter
2026-02-19 16:14 Re: DOCS - Add introductory paragraph to Getting Started chapter David G. Johnston <[email protected]>
2026-02-19 17:04 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Dragos Andriciuc <[email protected]>
@ 2026-02-26 08:48 ` Chao Li <[email protected]>
2026-02-27 16:28 ` Re: DOCS - Add introductory paragraph to Getting Started chapter David G. Johnston <[email protected]>
0 siblings, 1 reply; 5+ messages in thread
From: Chao Li @ 2026-02-26 08:48 UTC (permalink / raw)
To: Dragos Andriciuc <[email protected]>; +Cc: David G. Johnston <[email protected]>; Philip Alger <[email protected]>; Andreas Karlsson <[email protected]>; pgsql-hackers
> 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/
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: DOCS - Add introductory paragraph to Getting Started chapter
2026-02-19 16:14 Re: DOCS - Add introductory paragraph to Getting Started chapter David G. Johnston <[email protected]>
2026-02-19 17:04 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Dragos Andriciuc <[email protected]>
2026-02-26 08:48 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Chao Li <[email protected]>
@ 2026-02-27 16:28 ` David G. Johnston <[email protected]>
2026-04-22 09:45 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Dragos Andriciuc <[email protected]>
0 siblings, 1 reply; 5+ messages in thread
From: David G. Johnston @ 2026-02-27 16:28 UTC (permalink / raw)
To: Chao Li <[email protected]>; +Cc: Dragos Andriciuc <[email protected]>; Philip Alger <[email protected]>; Andreas Karlsson <[email protected]>; pgsql-hackers
On Thu, Feb 26, 2026 at 1:49 AM Chao Li <[email protected]> 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.
David J.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: DOCS - Add introductory paragraph to Getting Started chapter
2026-02-19 16:14 Re: DOCS - Add introductory paragraph to Getting Started chapter David G. Johnston <[email protected]>
2026-02-19 17:04 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Dragos Andriciuc <[email protected]>
2026-02-26 08:48 ` Re: DOCS - Add introductory paragraph to Getting Started chapter Chao Li <[email protected]>
2026-02-27 16:28 ` Re: DOCS - Add introductory paragraph to Getting Started chapter David G. Johnston <[email protected]>
@ 2026-04-22 09:45 ` Dragos Andriciuc <[email protected]>
0 siblings, 0 replies; 5+ messages in thread
From: Dragos Andriciuc @ 2026-04-22 09:45 UTC (permalink / raw)
To: Tom Lane <[email protected]>; David G. Johnston <[email protected]>; +Cc: Chao Li <[email protected]>; Philip Alger <[email protected]>; Andreas Karlsson <[email protected]>; pgsql-hackers
Hello Tom,
Thank you for the review, I agree with you.
For this patch, I focused on Chapter 1 to improve the initial onboarding experience, but you’re right that Chapters 2 and 3 would benefit from introductory paragraphs as well.
I will address these in a follow up update to keep the structure consistent and intact in the tutorial.
I appreciate the feedback.
Best regards,
Dragos
________________________________
From: Tom Lane <[email protected]>
Sent: Thursday, March 26, 2026 8:14 PM
To: David G. Johnston <[email protected]>
Cc: Chao Li <[email protected]>; Dragos Andriciuc <[email protected]>; Philip Alger <[email protected]>; Andreas Karlsson <[email protected]>; [email protected] <[email protected]>
Subject: Re: DOCS - Add introductory paragraph to Getting Started chapter
"David G. Johnston" <[email protected]> writes:
> On Thu, Feb 26, 2026 at 1:49 AM Chao Li <[email protected]> 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
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2026-04-22 09:45 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-02-19 16:14 Re: DOCS - Add introductory paragraph to Getting Started chapter David G. Johnston <[email protected]>
2026-02-19 17:04 ` Dragos Andriciuc <[email protected]>
2026-02-26 08:48 ` Chao Li <[email protected]>
2026-02-27 16:28 ` David G. Johnston <[email protected]>
2026-04-22 09:45 ` Dragos Andriciuc <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox