Re: [PATCH] Improvements to "Getting started" tutorial for GoogleCode-in task

 

I’m a student taking part in Google Code-in 2018. The task I am currently working on, https://codein.withgoogle.com/dashboard/task-instances/6406170207059968/, requires that I review and improve the “Getting Started” tutorial in the PostgreSQL docs, and submit a patch to this mailing list.

Thank you for picking up this task.

After reviewing the documentation, I found some parts to be slightly unclear. For example, in section 1.3 on creating databases, I found “no response” a bit unclear or ambiguous, so I replaced it with “exit without any error messages”.

 

After some experimentation, I found that a part of the documentation was incorrect. In Section 1.3, it was stated that “Database names must have an alphabetic first character”. However, I was able to create databases with names like “1234”, “$” or even “😀😀”. Hence, I decided to remove that sentence.

 

A diff of my changes is attached.

+    then one or more of the packages <productname>PostgreSQL</productname> requires is not installed.
+    See <xref linkend="install-requirements"/> for the required packages.


How about:

then packages which are required to build
<productname>PostgreSQL</productname> are missing.
See <xref linkend="install-requirements"/> for a list of requirements.




     If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
+    is already available for your experimentation,
+    you can install it yourself.  Doing so is not
     hard and it can be a good exercise.


This change does not make much sense, given that you leave the
second part of the sentence.



     As is typical of client/server applications, the client and the
-    server can be on different hosts.  In that case they communicate
+    server can be on different machines or networks.  In that case they communicate
     over a TCP/IP network connection.  You should keep this in mind,

I think "hosts" is preferred here. The differentiation between machines
and networks is not necessary.




-    The path at your site might be different.  Contact your site
+    The path at your site's server might be different.  Contact your site
     administrator or check the installation instructions to

Dunno if this change improves the wording, or the understanding.
How about replacing "site" with "installation"?



     <productname>PostgreSQL</productname> allows you to create any
-    number of databases at a given site.  Database names must have an
-    alphabetic first character and are limited to 63 bytes in
-    length.  A convenient choice is to create a database with the same
-    name as your current user name.  Many tools assume that database
-    name as the default, so it can save you some typing.  To create
-    that database, simply type:
+    number of databases at a given site.  Database names are limited to 63 bytes in
+    length. Database names longer than 63 bytes will be truncated. A convenient
+    choice is to create a database with the same name as your current user name.
+    Many tools assume that database name as the default, so it
+    can save you some typing. To create that database, simply type:

The part about "truncate" is correct, maybe you can include NAMEDATALEN here as well.

The part about the first character is correct - except you quote the name.
Then any name is allowed. If you rewrite this part, maybe include this as well.


The other changes look good.

-- 			Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project