Thread: GSoD - a patch for Getting Started tutorial

On Sun, 2019-11-17 at 00:04 +0300, Liudmila Mantrova wrote:
> Some time ago I was selected to participate in Google season of docs program to update
> the introductory tutorial. Please consider the attached patch for the Getting Started part.
> Keeping the original information, i tried to make it easy to follow, as well as added
> installation steps for binary packages. I'll be glad to hear your feedback.
> 
> Many thanks to Alexander Lakhin for responding to my multiple questions and verifying technical correctness.

This is a good thing; I have seen people complain about the tutorial
(https://www.postgresql.eu/events/pgconfeu2019/schedule/session/2735-whats-wrong-with-postgres/).
I really hope that your work doesn't go to waste.

I am a bit uncomfortable about having details about the workings of
binary packages for specific operating systems in the core documentation.
Maybe I'm too sensitive there, but what about having these parts in the Wiki
and linking there from the tutorial?

Quickly skimming over the text, I have two things to comment:
- The RedHat binaries use "trust" authentication by default, not "peer".
- I couldn't see anything about Windows.
  I think that particularly on Windows people would need a tutorial most,
  not because Windows people are more clueless, but because things work
  differently there.  Many Windows users don't know how to start a shell.

Yours,
Laurenz Albe

On Mon, 2019-11-18 at 23:35 +0300, Liudmila Mantrova wrote:
> > I am a bit uncomfortable about having details about the workings of
> > binary packages for specific operating systems in the core documentation.
> > Maybe I'm too sensitive there, but what about having these parts in the Wiki
> > and linking there from the tutorial?
> 
> I also had my doubts about it, but since we are only talking about PGDG packages that
> the community supports, it's probably OK to have it in docs? Besides, I believe we
> should be consistent here - if we are hand-holding the user through the source install,
> we should have a description for binary install as well (which is even more useful for novices).
> I also think it makes the tutorial self-contained, which seems to address one of the
> concerns raised in the presentation you are referring to.

Perhaps you are right, but I wonder if following a link into the Wiki
would be a great hurdle for the novice.
I personally thought that a lot of the complaints in the presentation
were ridiculous, so we need not follow its recommendations slavishly. 

> > Quickly skimming over the text, I have two things to comment:
> > - The RedHat binaries use "trust" authentication by default, not "peer".
>
> Do you mean PGDG binaries or any other binaries? For a PGDG install on e.g. RHEL 8,
> peer seems to be the default.
> But now that you mentioned it, I realized that trust is the default for
> source installs and it might be worth adding, too. I'll try to tweak this part again.

The binaries for Fedora Linux use "trust".

I think that the source installation is covered well enough.
 
> > - I couldn't see anything about Windows.
> >   I think that particularly on Windows people would need a tutorial most,
> >   not because Windows people are more clueless, but because things work
> >   differently there.  Many Windows users don't know how to start a shell.
>  
> I think we can extend it with Windows specifics if there are no other major concerns.
> (But it'll probably take some time for me to try it and figure out the differences.
> Although I know how to start a shell, I'm sure I'll face other problems. :))

I understand your reluctance.
But if we want to cater for clueless beginners, we cannot omit Windows.

Yours,
Laurenz Albe
-- 
Cybertec | https://www.cybertec-postgresql.com

Liudmila Mantrova <l.mantrova@gmail.com> writes:
> On Tue, Nov 19, 2019 at 11:00 AM Laurenz Albe <laurenz.albe@cybertec.at>
> wrote:
>> On Mon, 2019-11-18 at 23:35 +0300, Liudmila Mantrova wrote:
>>> I am a bit uncomfortable about having details about the workings of
>>> binary packages for specific operating systems in the core
>>> documentation.
>>> Maybe I'm too sensitive there, but what about having these parts in
>>> the Wiki and linking there from the tutorial?

>> I also had my doubts about it, but since we are only talking about PGDG
>> packages that the community supports, it's probably OK to have it in
>> docs?

> i'm all for linking to the download page for the exact install commands
> (which I did), but i see no harm in mentioning e.g. install/data
> directories in documentation. It is something I myself went back to when
> working on this tutorial update, so I believe the user will do too. But
> let's hope we'll hear other opinions as well before I go and rework it all.

Traditionally we've stayed away from this on the grounds that we don't
control packaging details and so we wouldn't know when whatever we say
becomes obsolete.  Moreover, packaging changes tend not to be quantized
to happen in sync with Postgres releases, so that even if we know
something changed, there'd be a delay to get the word out.

Maybe those arguments can be discounted if the proposal is *only* to
document the PGDG packages, but will such a restricted solution really
satisfy anyone?  I'm concerned that novices will not realize that the
presented details don't apply to whatever vendor-supplied Postgres
they are using.  This thread already presents a great example in its
confusion over what the default auth method is on Red Hat packages.

>> But if we want to cater for clueless beginners, we cannot omit Windows.

I have to agree with this point ... fortunately, there's probably only
one packaging that's of great interest there, and that's EDB's.

            regards, tom lane

On Tue, 2019-11-19 at 18:22 +0300, Liudmila Mantrova wrote:
> > The binaries for Fedora Linux use "trust".
> 
> Fedora 31 seems to be using peer. What am I missing?
> 
> [root@localhost ~]# /usr/pgsql-12/bin/postgresql-12-setup initdb
> Initializing database ... OK
> ...
> [root@localhost ~]# grep '^local' /var/lib/pgsql/12/data/pg_hba.conf
> local   all             all                                     peer
> local   replication     all                                     peer

I never realized that there is a "postgresql-12-setup" script included
in these packages.

I have always used "initdb" directly, and if I don't specify the -A
option explicitly, I get "trust".

Yours,
Laurenz Albe

On Tue, 2019-11-19 at 10:58 -0500, Tom Lane wrote:
> > i'm all for linking to the download page for the exact install commands
> > (which I did), but i see no harm in mentioning e.g. install/data
> > directories in documentation. It is something I myself went back to when
> > working on this tutorial update, so I believe the user will do too. But
> > let's hope we'll hear other opinions as well before I go and rework it all.
> 
> Traditionally we've stayed away from this on the grounds that we don't
> control packaging details and so we wouldn't know when whatever we say
> becomes obsolete.  Moreover, packaging changes tend not to be quantized
> to happen in sync with Postgres releases, so that even if we know
> something changed, there'd be a delay to get the word out.
> 
> Maybe those arguments can be discounted if the proposal is *only* to
> document the PGDG packages, but will such a restricted solution really
> satisfy anyone?  I'm concerned that novices will not realize that the
> presented details don't apply to whatever vendor-supplied Postgres
> they are using.  This thread already presents a great example in its
> confusion over what the default auth method is on Red Hat packages.

The confusion was my fault because I didn't follow the tutorial,
but the point is valid (others may make similar blunders).

I think that the danger of changing paths in the PGDG binaries is
limited.

It might be a good idea to provide links to the documentation of
other popular binary distributions, e.g. for MacOS.  We can add a
disclaimer that details can differ on these platforms.

I kind of like the "troubleshooting" section, but I am unsure where
to set the limit.  What is there currently doesn't cover all
potential causes (e.g., connection via TCP, see Windows), but
being exhaustive is probably impossible and not even desirable.

On the one hand I can see this section as being helpful for the
host of people who are having problems connecting, on the other hand
the true beginner might have trouble understanding explanations
containing terms like "absolute path" and "Unix-domain sockets".

(Side remark: I think the spelling should be "UNIX domain sockets".)


I'd be sorry if this effort goes to waste, and there are valuable
additions here.

I think that the material in this patch is an improvement over
the "Installation" section in the current tutorial, but that the
other sections ("Architectural Fundamentals", "Creating a Database"
and "Accessing a Database") are better in the original.

And I like the idea of a "troubleshooting" section.

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:
> I kind of like the "troubleshooting" section, but I am unsure where
> to set the limit.  What is there currently doesn't cover all
> potential causes (e.g., connection via TCP, see Windows), but
> being exhaustive is probably impossible and not even desirable.

> On the one hand I can see this section as being helpful for the
> host of people who are having problems connecting, on the other hand
> the true beginner might have trouble understanding explanations
> containing terms like "absolute path" and "Unix-domain sockets".

As far as that goes, Corey's nearby proposal to add a glossary
could be a great help.  We could define such terms there, and
make the tutorial's uses of them be hyperlinks.  So maybe we
should get that done first, and then come back to this?

> (Side remark: I think the spelling should be "UNIX domain sockets".)

FWIW, I think we've used the first spelling in most places.
Which is more "correct", I don't know, but I'm pretty sure
that spelling Unix in all-caps has been out of fashion for
a very long time.

            regards, tom lane