pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedreadability changes to postgres.sgml
14+ messages / 7 participants
[nested] [flat]
* readability changes to postgres.sgml
@ 2019-08-15 19:30 Joshua D. Drake <jd@commandprompt.com>
0 siblings, 1 reply; 14+ messages in thread
From: Joshua D. Drake @ 2019-08-15 19:30 UTC (permalink / raw)
To: pgsql-docs
attached
Thanks,
JD
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
Attachments:
[text/x-patch] postgres.diff (8.5K, ../../5ac2c96d-37a6-18aa-08c4-327a6fbff24b@commandprompt.com/2-postgres.diff)
download | inline diff:
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba7997..9f78a62ed8 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -31,24 +31,22 @@
<partintro>
<para>
Welcome to the <productname>PostgreSQL</productname> Tutorial. The
- following few chapters are intended to give a simple introduction
+ tutorial is intended to give an introduction
to <productname>PostgreSQL</productname>, relational database
- concepts, and the SQL language to those who are new to any one of
- these aspects. We only assume some general knowledge about how to
- use computers. No particular Unix or programming experience is
- required. This part is mainly intended to give you some hands-on
- experience with important aspects of the
- <productname>PostgreSQL</productname> system. It makes no attempt
- to be a complete or thorough treatment of the topics it covers.
+ concepts, and the SQL language. We assume some general knowledge about
+ how to use computers and no particular Unix or programming experience is
+ required. This tutorial is intended to provide hands-on experience with
+ important aspects of the <productname>PostgreSQL</productname> system.
+ It makes no attempt to be a comprehensive treatment of the topics it covers.
</para>
<para>
- After you have worked through this tutorial you might want to move
- on to reading <xref linkend="sql"/> to gain a more formal knowledge
+ After you have successfully completed this tutorial you will want to
+ read the <xref linkend="sql"/> section to gain a better understanding
of the SQL language, or <xref linkend="client-interfaces"/> for
- information about developing applications for
- <productname>PostgreSQL</productname>. Those who set up and
- manage their own server should also read <xref linkend="admin"/>.
+ information about developing applications with
+ <productname>PostgreSQL</productname>. Those who provision and
+ manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
</para>
</partintro>
@@ -66,28 +64,26 @@
This part describes the use of the <acronym>SQL</acronym> language
in <productname>PostgreSQL</productname>. We start with
describing the general syntax of <acronym>SQL</acronym>, then
- explain how to create the structures to hold data, how to populate
- the database, and how to query it. The middle part lists the
- available data types and functions for use in
- <acronym>SQL</acronym> commands. The rest treats several
- aspects that are important for tuning a database for optimal
- performance.
+ how to create tables, how to populate the database, and how to
+ query it. The middle part lists the available data types and
+ functions for use in <acronym>SQL</acronym> commands. Lasty,
+ we address several aspects of importantance for tuning a database.
</para>
<para>
- The information in this part is arranged so that a novice user can
- follow it start to end to gain a full understanding of the topics
+ The information is arranged so that a novice user can
+ follow it from start to end and gain a full understanding of the topics
without having to refer forward too many times. The chapters are
intended to be self-contained, so that advanced users can read the
- chapters individually as they choose. The information in this
- part is presented in a narrative fashion in topical units.
- Readers looking for a complete description of a particular command
- should see <xref linkend="reference"/>.
+ chapters individually as they choose. The information is presented
+ in narrative form with topical units. Readers looking for a complete
+ description of a particular command are encouraged to review
+ the <xref linkend="reference"/>.
</para>
<para>
- Readers of this part should know how to connect to a
- <productname>PostgreSQL</productname> database and issue
+ Readers should know how to connect to a
+ <productname>PostgreSQL</productname> database and issue
<acronym>SQL</acronym> commands. Readers that are unfamiliar with
these issues are encouraged to read <xref linkend="tutorial"/>
first. <acronym>SQL</acronym> commands are typically entered
@@ -118,32 +114,32 @@
<partintro>
<para>
This part covers topics that are of interest to a
- <productname>PostgreSQL</productname> database administrator. This includes
- installation of the software, set up and configuration of the
- server, management of users and databases, and maintenance tasks.
- Anyone who runs a <productname>PostgreSQL</productname> server, even for
+ <productname>PostgreSQL</productname> administrator. This includes
+ installation, configuration of the server, management of users
+ and databases, and maintenance tasks. Anyone running
+ <productname>PostgreSQL</productname> server, even for
personal use, but especially in production, should be familiar
- with the topics covered in this part.
+ with these topics.
</para>
<para>
- The information in this part is arranged approximately in the
- order in which a new user should read it. But the chapters are
- self-contained and can be read individually as desired. The
- information in this part is presented in a narrative fashion in
- topical units. Readers looking for a complete description of a
- particular command should see <xref linkend="reference"/>.
+ The information attempts to be in the order in which
+ a new user should read it. The chapters are self-contained and
+ can be read individually as desired. The information is presented
+ in a narrative form in topical units. Readers looking for a complete
+ description of a command are encouraged to review the
+ <xref linkend="reference"/>.
</para>
<para>
The first few chapters are written so they can be understood
without prerequisite knowledge, so new users who need to set
- up their own server can begin their exploration with this part.
- The rest of this part is about tuning and management; that material
+ up their own server can begin their exploration. The rest of this
+ part is about tuning and management; that material
assumes that the reader is familiar with the general use of
the <productname>PostgreSQL</productname> database system. Readers are
- encouraged to look at <xref linkend="tutorial"/> and <xref
- linkend="sql"/> for additional information.
+ encouraged review the <xref linkend="tutorial"/> and <xref
+ linkend="sql"/> parts for additional information.
</para>
</partintro>
@@ -174,13 +170,13 @@
<para>
This part describes the client programming interfaces distributed
with <productname>PostgreSQL</productname>. Each of these chapters can be
- read independently. Note that there are many other programming
- interfaces for client programs that are distributed separately and
+ read independently. There are many extrernal programming
+ interfaces for client programs that are distributed separately. They
contain their own documentation (<xref linkend="external-projects"/>
lists some of the more popular ones). Readers of this part should be
- familiar with using <acronym>SQL</acronym> commands to manipulate
+ familiar with using <acronym>SQL</acronym> to manipulate
and query the database (see <xref linkend="sql"/>) and of course
- with the programming language that the interface uses.
+ with the programming language of their choice.
</para>
</partintro>
@@ -198,15 +194,15 @@
<para>
This part is about extending the server functionality with
user-defined functions, data types, triggers, etc. These are
- advanced topics which should probably be approached only after all
+ advanced topics which should be approached only after all
the other user documentation about <productname>PostgreSQL</productname> has
been understood. Later chapters in this part describe the server-side
programming languages available in the
<productname>PostgreSQL</productname> distribution as well as
- general issues concerning server-side programming languages. It
+ general issues concerning server-side programming. It
is essential to read at least the earlier sections of <xref
linkend="extend"/> (covering functions) before diving into the
- material about server-side programming languages.
+ material about server-side programming.
</para>
</partintro>
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-16 00:26 Stephen Frost <sfrost@snowman.net>
parent: Joshua D. Drake <jd@commandprompt.com>
0 siblings, 2 replies; 14+ messages in thread
From: Stephen Frost @ 2019-08-16 00:26 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: pgsql-docs
Greetings,
* Joshua D. Drake (jd@commandprompt.com) wrote:
> attached
While I'm all for working on improving the documentation and, in
particular, our tutorials, the above description of what the suggested
change is seems to be rather.. lacking, and the changes themselves
don't come across as obvious or clear improvements (and in some cases
they seem to be simply removing words and removing content that is
actually important and valuable, making it a net negative change).
Specifically-
> Welcome to the <productname>PostgreSQL</productname> Tutorial. The
> - following few chapters are intended to give a simple introduction
> + tutorial is intended to give an introduction
> to <productname>PostgreSQL</productname>, relational database
I disagree with removing 'simple'- after all, that's exactly what we
want this tutorial to be and including that hopefully encourages
individuals to move forward. I'd argue the same applies to pointing out
that the tutorial itself is only a few chapters and isn't the whole rest
of the documentation.
> - concepts, and the SQL language to those who are new to any one of
> - these aspects. We only assume some general knowledge about how to
> - use computers. No particular Unix or programming experience is
> - required. This part is mainly intended to give you some hands-on
> - experience with important aspects of the
> - <productname>PostgreSQL</productname> system. It makes no attempt
> - to be a complete or thorough treatment of the topics it covers.
> + concepts, and the SQL language. We assume some general knowledge about
> + how to use computers and no particular Unix or programming experience is
> + required. This tutorial is intended to provide hands-on experience with
> + important aspects of the <productname>PostgreSQL</productname> system.
> + It makes no attempt to be a comprehensive treatment of the topics it covers.
> </para>
This seems to primairly just remove the "who are new to any one of those
aspects" but that's pretty key to the goal of this tutorial and it
speaks to how we should be thinking about the rest of this part of the
documentation.
> <para>
> - After you have worked through this tutorial you might want to move
> - on to reading <xref linkend="sql"/> to gain a more formal knowledge
> + After you have successfully completed this tutorial you will want to
> + read the <xref linkend="sql"/> section to gain a better understanding
> of the SQL language, or <xref linkend="client-interfaces"/> for
> - information about developing applications for
> - <productname>PostgreSQL</productname>. Those who set up and
> - manage their own server should also read <xref linkend="admin"/>.
> + information about developing applications with
> + <productname>PostgreSQL</productname>. Those who provision and
> + manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
> </para>
> </partintro>
Why change "might" to "will"..? Or remove "formal"? Also not sure
about changing "set up" to "provision", the latter seems to imply a
particular environment while the former doesn't.
> @@ -66,28 +64,26 @@
> This part describes the use of the <acronym>SQL</acronym> language
> in <productname>PostgreSQL</productname>. We start with
> describing the general syntax of <acronym>SQL</acronym>, then
> - explain how to create the structures to hold data, how to populate
> - the database, and how to query it. The middle part lists the
> - available data types and functions for use in
> - <acronym>SQL</acronym> commands. The rest treats several
> - aspects that are important for tuning a database for optimal
> - performance.
> + how to create tables, how to populate the database, and how to
> + query it. The middle part lists the available data types and
> + functions for use in <acronym>SQL</acronym> commands. Lasty,
> + we address several aspects of importantance for tuning a database.
> </para>
The term "structures to hold data" seems to be specifically used because
we haven't yet defined what a 'table' is, so I don't agree with this
change either.
The later changes seem to be in a similar vein.. Dropping things like
"language" when talking about server-side programming languages,
removing references to "in this part" or changing them to be "in this
tutorial" or similar, and just don't strike me as particularly good
improvements or ones which have a specific direction or a defined reason
for being made.
Thanks,
Stephen
Attachments:
[application/pgp-signature] signature.asc (818B, ../../20190816002623.GS16436@tamriel.snowman.net/2-signature.asc)
download
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-16 05:22 Erik Rijkers <er@xs4all.nl>
parent: Stephen Frost <sfrost@snowman.net>
1 sibling, 3 replies; 14+ messages in thread
From: Erik Rijkers @ 2019-08-16 05:22 UTC (permalink / raw)
To: Stephen Frost <sfrost@snowman.net>; +Cc: Joshua D. Drake <jd@commandprompt.com>; pgsql-docs
On 2019-08-16 02:26, Stephen Frost wrote:
> Greetings,
>
> * Joshua D. Drake (jd@commandprompt.com) wrote:
>> attached
> they seem to be simply removing words and removing content that is
For what it's worth, I think the proposed changes are all solid
improvements. The text reads better with them, and that's what this is
about -- not whether the removed little text-pieces were 'true' or not.
However, there is one typo:
+ read independently. There are many extrernal programming
extrernal -> external
(and I would say that dropping that word 'external' would be another
little improvement)
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-16 17:41 Liudmila Mantrova <l.mantrova@gmail.com>
parent: Erik Rijkers <er@xs4all.nl>
2 siblings, 1 reply; 14+ messages in thread
From: Liudmila Mantrova @ 2019-08-16 17:41 UTC (permalink / raw)
To: Erik Rijkers <er@xs4all.nl>; Stephen Frost <sfrost@snowman.net>; +Cc: Joshua D. Drake <jd@commandprompt.com>; pgsql-docs
>
> For what it's worth, I think the proposed changes are all solid
> improvements. The text reads better with them, and that's what this is
> about -- not whether the removed little text-pieces were 'true' or not.
>
>
I'm afraid I can't agree that all changes are good enough (e.g. "start with
describing the general syntax of <acronym>SQL</acronym>, then how to create
tables.." used to be better with a verb, and "Readers are encouraged
review" is probably too liberal grammar). Changes like "encouraged to look"
vs. the original "should see" can be also challenged as an improvement -
IMHO the original version reads equally well (although it could be more
concise for sure).
That said, I agree we should not hold on to every word just because it was
written - the shorter the docs, the more chances they get to be actually
read. Avoiding assumptions about what's simple may also be beneficial. A
simple concept for one can be new and unclear to another, no matter how
experienced they actually are.
If we want to make these intros more concise, one of the easiest ways to
achieve this is to address the reader directly ("Readers looking for xxx
are encouraged to look" vs. smth like "For xxx, see"). We can also question
the need for some of the provided info - for example, assumptions about
typical user behavior and complexity of the text that follows could
probably be let gone altogether. I don't believe they can actually guide
anyone as they are quite vague anyway (how many are "the first few"
chapters exactly?) That would leave us with the scope of the chapters
described and explicit references to elsewhere (if required for clarity),
making the most valuable parts here more prominent and not-so-easy to skip.
--
Best regards,
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-17 04:38 Erik Rijkers <er@xs4all.nl>
parent: Erik Rijkers <er@xs4all.nl>
2 siblings, 1 reply; 14+ messages in thread
From: Erik Rijkers @ 2019-08-17 04:38 UTC (permalink / raw)
To: Stephen Frost <sfrost@snowman.net>; +Cc: Joshua D. Drake <jd@commandprompt.com>; pgsql-docs
On 2019-08-16 07:22, Erik Rijkers wrote:
> On 2019-08-16 02:26, Stephen Frost wrote:
>> Greetings,
>>
>> * Joshua D. Drake (jd@commandprompt.com) wrote:
>>> attached
>
>> they seem to be simply removing words and removing content that is
>
> For what it's worth, I think the proposed changes are all solid
> improvements. The text reads better with them, and that's what this is
> about -- not whether the removed little text-pieces were 'true' or
> not.
>
>
> However, there is one typo:
>
> + read independently. There are many extrernal programming
>
> extrernal -> external
> (and I would say that dropping that word 'external' would be another
> little improvement)
and:
Lasty -> Lastly
importantance -> importance
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-19 17:14 Joshua D. Drake <jd@commandprompt.com>
parent: Erik Rijkers <er@xs4all.nl>
2 siblings, 0 replies; 14+ messages in thread
From: Joshua D. Drake @ 2019-08-19 17:14 UTC (permalink / raw)
To: Erik Rijkers <er@xs4all.nl>; Stephen Frost <sfrost@snowman.net>; +Cc: pgsql-docs
On 8/15/19 10:22 PM, Erik Rijkers wrote:
> On 2019-08-16 02:26, Stephen Frost wrote:
>> Greetings,
>>
>> * Joshua D. Drake (jd@commandprompt.com) wrote:
>>> attached
>
>> they seem to be simply removing words and removing content that is
>
> For what it's worth, I think the proposed changes are all solid
> improvements. The text reads better with them, and that's what this is
> about -- not whether the removed little text-pieces were 'true' or not.
Correct, the point of these patches is to make the documentation
succinct and hopefully more clear. Any writing class you take will tell
you that the less words you can use to make the point, the better.
Further, language interpretation changes over time and certain
adjectives will not have the impact they once did. As I have been
reviewing the docs, the language used although correct is often clumsy.
>
> However, there is one typo:
>
> + read independently. There are many extrernal programming
>
> extrernal -> external
> (and I would say that dropping that word 'external' would be another
> little improvement)
>
Good catch, should I submit a new patch or will it be fixed if applied?
JD
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-19 17:15 Joshua D. Drake <jd@commandprompt.com>
parent: Liudmila Mantrova <l.mantrova@gmail.com>
0 siblings, 0 replies; 14+ messages in thread
From: Joshua D. Drake @ 2019-08-19 17:15 UTC (permalink / raw)
To: Liudmila Mantrova <l.mantrova@gmail.com>; Erik Rijkers <er@xs4all.nl>; Stephen Frost <sfrost@snowman.net>; +Cc: pgsql-docs
On 8/16/19 10:41 AM, Liudmila Mantrova wrote:
>
>
> For what it's worth, I think the proposed changes are all solid
> improvements. The text reads better with them, and that's what
> this is
> about -- not whether the removed little text-pieces were 'true' or
> not.
>
> If we want to make these intros more concise, one of the easiest ways
> to achieve this is to address the reader directly ("Readers looking
> for xxx are encouraged to look" vs. smth like "For xxx, see").
This is true and my counter argument is that a call to action is more
likely to get the reader to do something.
JD
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-19 19:16 Joshua D. Drake <jd@commandprompt.com>
parent: Stephen Frost <sfrost@snowman.net>
1 sibling, 0 replies; 14+ messages in thread
From: Joshua D. Drake @ 2019-08-19 19:16 UTC (permalink / raw)
To: Stephen Frost <sfrost@snowman.net>; +Cc: pgsql-docs
On 8/15/19 5:26 PM, Stephen Frost wrote:
>
> Specifically-
>
>> Welcome to the <productname>PostgreSQL</productname> Tutorial. The
>> - following few chapters are intended to give a simple introduction
>> + tutorial is intended to give an introduction
>> to <productname>PostgreSQL</productname>, relational database
> I disagree with removing 'simple'- after all, that's exactly what we
> want this tutorial to be and including that hopefully encourages
> individuals to move forward. I'd argue the same applies to pointing out
> that the tutorial itself is only a few chapters and isn't the whole rest
> of the documentation.
I would argue the use of the word introduction implicitly suggests the
unneeded word, "simple".
>> - concepts, and the SQL language to those who are new to any one of
>> - these aspects. We only assume some general knowledge about how to
>> - use computers. No particular Unix or programming experience is
>> - required. This part is mainly intended to give you some hands-on
>> - experience with important aspects of the
>> - <productname>PostgreSQL</productname> system. It makes no attempt
>> - to be a complete or thorough treatment of the topics it covers.
>> + concepts, and the SQL language. We assume some general knowledge about
>> + how to use computers and no particular Unix or programming experience is
>> + required. This tutorial is intended to provide hands-on experience with
>> + important aspects of the <productname>PostgreSQL</productname> system.
>> + It makes no attempt to be a comprehensive treatment of the topics it covers.
>> </para>
> This seems to primairly just remove the "who are new to any one of those
> aspects" but that's pretty key to the goal of this tutorial and it
> speaks to how we should be thinking about the rest of this part of the
> documentation.
I do not believe that is true. We clearly state, "It makes no attempt to
be a complete or thorough treatment of the topics it covers. concepts,
and the SQL language". Adding "who are new to any one of those aspects"
is redundant when read in context of the content.
>
>> <para>
>> - After you have worked through this tutorial you might want to move
>> - on to reading <xref linkend="sql"/> to gain a more formal knowledge
>> + After you have successfully completed this tutorial you will want to
>> + read the <xref linkend="sql"/> section to gain a better understanding
>> of the SQL language, or <xref linkend="client-interfaces"/> for
>> - information about developing applications for
>> - <productname>PostgreSQL</productname>. Those who set up and
>> - manage their own server should also read <xref linkend="admin"/>.
>> + information about developing applications with
>> + <productname>PostgreSQL</productname>. Those who provision and
>> + manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
>> </para>
>> </partintro>
> Why change "might" to "will"..? Or remove "formal"? Also not sure
> about changing "set up" to "provision", the latter seems to imply a
> particular environment while the former doesn't.
A call to action should be formal. Using "might" concludes that they may
not need more information. We want to definitely encourage people to
read more documentation.
The use of the word formal is just not needed. We already state they
will gain more knowledge, why do we need the word formal at all?
>
>> @@ -66,28 +64,26 @@
>> This part describes the use of the <acronym>SQL</acronym> language
>> in <productname>PostgreSQL</productname>. We start with
>> describing the general syntax of <acronym>SQL</acronym>, then
>> - explain how to create the structures to hold data, how to populate
>> - the database, and how to query it. The middle part lists the
>> - available data types and functions for use in
>> - <acronym>SQL</acronym> commands. The rest treats several
>> - aspects that are important for tuning a database for optimal
>> - performance.
>> + how to create tables, how to populate the database, and how to
>> + query it. The middle part lists the available data types and
>> + functions for use in <acronym>SQL</acronym> commands. Lasty,
>> + we address several aspects of importantance for tuning a database.
>> </para>
> The term "structures to hold data" seems to be specifically used because
> we haven't yet defined what a 'table' is, so I don't agree with this
> change either.
Interesting, there may be a point here but I would say that it is likely
the user knows what a table is and if not, they can "insert search
engine or dictionary here). I could see an argument for "data table" or
"database table". I removed "structures to hold data" because it says
literally nothing. What structure? Is this a barrel, a building, a car?
If we keep that sentence then I believe we should define it right there,
it should be "structures to hold data (table)" or something.
> The later changes seem to be in a similar vein.. Dropping things like
> "language" when talking about server-side programming languages,
> removing references to "in this part" or changing them to be "in this
> tutorial" or similar, and just don't strike me as particularly good
> improvements or ones which have a specific direction or a defined reason
> for being made.
As others have mentioned, it improves readability. We should be using
exactly the amount of words needed to describe "whatever", no more, no
less. The more words, the more there is open for interpretation and
confusion.
JD
> Thanks,
>
> Stephen
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-19 23:00 Joshua D. Drake <jd@commandprompt.com>
parent: Erik Rijkers <er@xs4all.nl>
0 siblings, 2 replies; 14+ messages in thread
From: Joshua D. Drake @ 2019-08-19 23:00 UTC (permalink / raw)
To: Erik Rijkers <er@xs4all.nl>; Stephen Frost <sfrost@snowman.net>; +Cc: pgsql-docs
Team,
New version attached with spelling errors fixed.
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
Attachments:
[text/x-patch] postgres.diff (8.5K, ../../317b2dec-264b-2085-fc9c-10f2feca3693@commandprompt.com/2-postgres.diff)
download | inline diff:
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba7997..a6b77d50eb 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -31,24 +31,22 @@
<partintro>
<para>
Welcome to the <productname>PostgreSQL</productname> Tutorial. The
- following few chapters are intended to give a simple introduction
+ tutorial is intended to give an introduction
to <productname>PostgreSQL</productname>, relational database
- concepts, and the SQL language to those who are new to any one of
- these aspects. We only assume some general knowledge about how to
- use computers. No particular Unix or programming experience is
- required. This part is mainly intended to give you some hands-on
- experience with important aspects of the
- <productname>PostgreSQL</productname> system. It makes no attempt
- to be a complete or thorough treatment of the topics it covers.
+ concepts, and the SQL language. We assume some general knowledge about
+ how to use computers and no particular Unix or programming experience is
+ required. This tutorial is intended to provide hands-on experience with
+ important aspects of the <productname>PostgreSQL</productname> system.
+ It makes no attempt to be a comprehensive treatment of the topics it covers.
</para>
<para>
- After you have worked through this tutorial you might want to move
- on to reading <xref linkend="sql"/> to gain a more formal knowledge
+ After you have successfully completed this tutorial you will want to
+ read the <xref linkend="sql"/> section to gain a better understanding
of the SQL language, or <xref linkend="client-interfaces"/> for
- information about developing applications for
- <productname>PostgreSQL</productname>. Those who set up and
- manage their own server should also read <xref linkend="admin"/>.
+ information about developing applications with
+ <productname>PostgreSQL</productname>. Those who provision and
+ manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
</para>
</partintro>
@@ -66,28 +64,26 @@
This part describes the use of the <acronym>SQL</acronym> language
in <productname>PostgreSQL</productname>. We start with
describing the general syntax of <acronym>SQL</acronym>, then
- explain how to create the structures to hold data, how to populate
- the database, and how to query it. The middle part lists the
- available data types and functions for use in
- <acronym>SQL</acronym> commands. The rest treats several
- aspects that are important for tuning a database for optimal
- performance.
+ how to create tables, how to populate the database, and how to
+ query it. The middle part lists the available data types and
+ functions for use in <acronym>SQL</acronym> commands. Lastly,
+ we address several aspects of importance for tuning a database.
</para>
<para>
- The information in this part is arranged so that a novice user can
- follow it start to end to gain a full understanding of the topics
+ The information is arranged so that a novice user can
+ follow it from start to end and gain a full understanding of the topics
without having to refer forward too many times. The chapters are
intended to be self-contained, so that advanced users can read the
- chapters individually as they choose. The information in this
- part is presented in a narrative fashion in topical units.
- Readers looking for a complete description of a particular command
- should see <xref linkend="reference"/>.
+ chapters individually as they choose. The information is presented
+ in narrative form with topical units. Readers looking for a complete
+ description of a particular command are encouraged to review
+ the <xref linkend="reference"/>.
</para>
<para>
- Readers of this part should know how to connect to a
- <productname>PostgreSQL</productname> database and issue
+ Readers should know how to connect to a
+ <productname>PostgreSQL</productname> database and issue
<acronym>SQL</acronym> commands. Readers that are unfamiliar with
these issues are encouraged to read <xref linkend="tutorial"/>
first. <acronym>SQL</acronym> commands are typically entered
@@ -118,32 +114,32 @@
<partintro>
<para>
This part covers topics that are of interest to a
- <productname>PostgreSQL</productname> database administrator. This includes
- installation of the software, set up and configuration of the
- server, management of users and databases, and maintenance tasks.
- Anyone who runs a <productname>PostgreSQL</productname> server, even for
+ <productname>PostgreSQL</productname> administrator. This includes
+ installation, configuration of the server, management of users
+ and databases, and maintenance tasks. Anyone running
+ <productname>PostgreSQL</productname> server, even for
personal use, but especially in production, should be familiar
- with the topics covered in this part.
+ with these topics.
</para>
<para>
- The information in this part is arranged approximately in the
- order in which a new user should read it. But the chapters are
- self-contained and can be read individually as desired. The
- information in this part is presented in a narrative fashion in
- topical units. Readers looking for a complete description of a
- particular command should see <xref linkend="reference"/>.
+ The information attempts to be in the order in which
+ a new user should read it. The chapters are self-contained and
+ can be read individually as desired. The information is presented
+ in a narrative form in topical units. Readers looking for a complete
+ description of a command are encouraged to review the
+ <xref linkend="reference"/>.
</para>
<para>
The first few chapters are written so they can be understood
without prerequisite knowledge, so new users who need to set
- up their own server can begin their exploration with this part.
- The rest of this part is about tuning and management; that material
+ up their own server can begin their exploration. The rest of this
+ part is about tuning and management; that material
assumes that the reader is familiar with the general use of
the <productname>PostgreSQL</productname> database system. Readers are
- encouraged to look at <xref linkend="tutorial"/> and <xref
- linkend="sql"/> for additional information.
+ encouraged review the <xref linkend="tutorial"/> and <xref
+ linkend="sql"/> parts for additional information.
</para>
</partintro>
@@ -174,13 +170,13 @@
<para>
This part describes the client programming interfaces distributed
with <productname>PostgreSQL</productname>. Each of these chapters can be
- read independently. Note that there are many other programming
- interfaces for client programs that are distributed separately and
+ read independently. There are many external programming
+ interfaces for client programs that are distributed separately. They
contain their own documentation (<xref linkend="external-projects"/>
lists some of the more popular ones). Readers of this part should be
- familiar with using <acronym>SQL</acronym> commands to manipulate
+ familiar with using <acronym>SQL</acronym> to manipulate
and query the database (see <xref linkend="sql"/>) and of course
- with the programming language that the interface uses.
+ with the programming language of their choice.
</para>
</partintro>
@@ -198,15 +194,15 @@
<para>
This part is about extending the server functionality with
user-defined functions, data types, triggers, etc. These are
- advanced topics which should probably be approached only after all
+ advanced topics which should be approached only after all
the other user documentation about <productname>PostgreSQL</productname> has
been understood. Later chapters in this part describe the server-side
programming languages available in the
<productname>PostgreSQL</productname> distribution as well as
- general issues concerning server-side programming languages. It
+ general issues concerning server-side programming. It
is essential to read at least the earlier sections of <xref
linkend="extend"/> (covering functions) before diving into the
- material about server-side programming languages.
+ material about server-side programming.
</para>
</partintro>
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-20 05:05 Michael Paquier <michael@paquier.xyz>
parent: Joshua D. Drake <jd@commandprompt.com>
1 sibling, 1 reply; 14+ messages in thread
From: Michael Paquier @ 2019-08-20 05:05 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: Erik Rijkers <er@xs4all.nl>; Stephen Frost <sfrost@snowman.net>; pgsql-docs
On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
> New version attached with spelling errors fixed.
I have gone through this patch, and I have a hard time understanding
why these are improvements over the existing wording. In what does
this make things better?
--
Michael
Attachments:
[application/pgp-signature] signature.asc (832B, ../../20190820050530.GC1841@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-20 05:36 Erik Rijkers <er@xs4all.nl>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 14+ messages in thread
From: Erik Rijkers @ 2019-08-20 05:36 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: Joshua D. Drake <jd@commandprompt.com>; Stephen Frost <sfrost@snowman.net>; pgsql-docs
On 2019-08-20 07:05, Michael Paquier wrote:
> On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
>> New version attached with spelling errors fixed.
>
> I have gone through this patch, and I have a hard time understanding
> why these are improvements over the existing wording. In what does
> this make things better?
It's pretty simple, it improves readability. It does so mainly by
removing unnecessary text.
+1
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2019-08-20 16:03 Joshua D. Drake <jd@commandprompt.com>
parent: Erik Rijkers <er@xs4all.nl>
0 siblings, 0 replies; 14+ messages in thread
From: Joshua D. Drake @ 2019-08-20 16:03 UTC (permalink / raw)
To: Erik Rijkers <er@xs4all.nl>; Michael Paquier <michael@paquier.xyz>; +Cc: Stephen Frost <sfrost@snowman.net>; pgsql-docs
On 8/19/19 10:36 PM, Erik Rijkers wrote:
> On 2019-08-20 07:05, Michael Paquier wrote:
>> On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
>>> New version attached with spelling errors fixed.
>>
>> I have gone through this patch, and I have a hard time understanding
>> why these are improvements over the existing wording. In what does
>> this make things better?
>
> It's pretty simple, it improves readability. It does so mainly by
> removing unnecessary text.
>
> +1
>
Thanks for jumping in Erik. Michael, one of the cornerstones of good
writing is that you should only use exactly as many words as needed to
convey your point accurately. The more words, the more room for
interpretation, confusion and error from the readers side. It is easy
for us to look at the docs and say, "They are fine". We aren't reading
these docs as someone brand new to the project.
In short, the simpler we make our docs without sacrificing accuracy the
easier the docs will be to comprehend.
JD
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2023-11-08 21:48 Bruce Momjian <bruce@momjian.us>
parent: Joshua D. Drake <jd@commandprompt.com>
1 sibling, 1 reply; 14+ messages in thread
From: Bruce Momjian @ 2023-11-08 21:48 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: Erik Rijkers <er@xs4all.nl>; Stephen Frost <sfrost@snowman.net>; pgsql-docs
On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
> Team,
>
> New version attached with spelling errors fixed.
After four years, patch applied to master. I know reviews had trouble
reviewing this, and I found git diff --word-diff=color to be very
helpful for this patch.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: readability changes to postgres.sgml
@ 2023-11-08 21:58 Joshua Drake <jd@commandprompt.com>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 14+ messages in thread
From: Joshua Drake @ 2023-11-08 21:58 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Erik Rijkers <er@xs4all.nl>; Stephen Frost <sfrost@snowman.net>; pgsql-docs
Blink... thanks!
and also for the tips.
On Wed, Nov 8, 2023 at 1:48 PM Bruce Momjian <bruce@momjian.us> wrote:
> On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
> > Team,
> >
> > New version attached with spelling errors fixed.
>
> After four years, patch applied to master. I know reviews had trouble
> reviewing this, and I found git diff --word-diff=color to be very
> helpful for this patch.
>
> --
> Bruce Momjian <bruce@momjian.us> https://momjian.us
> EDB https://enterprisedb.com
>
> Only you can decide what is important to you.
>
^ permalink raw reply [nested|flat] 14+ messages in thread
end of thread, other threads:[~2023-11-08 21:58 UTC | newest]
Thread overview: 14+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-08-15 19:30 readability changes to postgres.sgml Joshua D. Drake <jd@commandprompt.com>
2019-08-16 00:26 ` Stephen Frost <sfrost@snowman.net>
2019-08-16 05:22 ` Erik Rijkers <er@xs4all.nl>
2019-08-16 17:41 ` Liudmila Mantrova <l.mantrova@gmail.com>
2019-08-19 17:15 ` Joshua D. Drake <jd@commandprompt.com>
2019-08-17 04:38 ` Erik Rijkers <er@xs4all.nl>
2019-08-19 23:00 ` Joshua D. Drake <jd@commandprompt.com>
2019-08-20 05:05 ` Michael Paquier <michael@paquier.xyz>
2019-08-20 05:36 ` Erik Rijkers <er@xs4all.nl>
2019-08-20 16:03 ` Joshua D. Drake <jd@commandprompt.com>
2023-11-08 21:48 ` Bruce Momjian <bruce@momjian.us>
2023-11-08 21:58 ` Joshua Drake <jd@commandprompt.com>
2019-08-19 17:14 ` Joshua D. Drake <jd@commandprompt.com>
2019-08-19 19:16 ` Joshua D. Drake <jd@commandprompt.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox