readability changes to postgres.sgml

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

readability changes to postgres.sgml

Joshua D. Drake
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.   *****


postgres.diff (8K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Stephen Frost
Greetings,

* Joshua D. Drake ([hidden email]) 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

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Erikjan Rijkers
On 2019-08-16 02:26, Stephen Frost wrote:
> Greetings,
>
> * Joshua D. Drake ([hidden email]) 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)



Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Liudmila Mantrova-2


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
Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Erikjan Rijkers
In reply to this post by Erikjan Rijkers
On 2019-08-16 07:22, Erik Rijkers wrote:

> On 2019-08-16 02:26, Stephen Frost wrote:
>> Greetings,
>>
>> * Joshua D. Drake ([hidden email]) 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













Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Joshua D. Drake
In reply to this post by Erikjan Rijkers
On 8/15/19 10:22 PM, Erik Rijkers wrote:

> On 2019-08-16 02:26, Stephen Frost wrote:
>> Greetings,
>>
>> * Joshua D. Drake ([hidden email]) 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.   *****



Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Joshua D. Drake
In reply to this post by Liudmila Mantrova-2
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.   *****



Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Joshua D. Drake
In reply to this post by Stephen Frost
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.   *****



Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Joshua D. Drake
In reply to this post by Erikjan Rijkers
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.   *****


postgres.diff (8K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Michael Paquier-2
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

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Erikjan Rijkers
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



Reply | Threaded
Open this post in threaded view
|

Re: readability changes to postgres.sgml

Joshua D. Drake
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.   *****