Re: readability changes to postgres.sgml - Mailing list 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