readability changes to postgres.sgml

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

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)

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

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

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. *****

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. *****

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. *****

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. *****

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

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

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. *****

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.

Blink... thanks!

and also for the tips.

On Wed, Nov 8, 2023 at 1:48 PM Bruce Momjian <bruce@momjian.us> wrote: