Re: readability changes to postgres.sgml

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