Message-ID: <2dd3a48be2f6b7b18631051b61e568fea98c10ec.camel@cybertec.at>
Subject: Re: GSoD - a patch for Getting Started tutorial
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Tom Lane <tgl@sss.pgh.pa.us>, Liudmila Mantrova <l.mantrova@gmail.com>
Cc: pgsql-docs@lists.postgresql.org, Stephen Frost <sfrost@snowman.net>,
	Sarah Conway Schnurr <xenophenes42@gmail.com>
Date: Wed, 20 Nov 2019 11:29:12 +0100
In-Reply-To: <9058.1574179093@sss.pgh.pa.us>
References: 
	<CAEkD-mAxCk_mX_RwjyxBLHEjt_T5-mS-c6ryfh3nBjdbyYMC0g@mail.gmail.com>
	 <54907b90aa20e603eb4204153c7dd5790ce258a4.camel@cybertec.at>
	 <CAEkD-mD-A1p=xZ7URBM4L5KUap63MQMYh9x1QTTtyFHX+5QcQQ@mail.gmail.com>
	 <ec20719e575c5cbe69cccf1616e80d9b47d43c18.camel@cybertec.at>
	 <CAEkD-mB2E90p_hH4qSkxqMQ1KDA_owy3zHz_V3zcwAxZVRKwDA@mail.gmail.com>
	 <9058.1574179093@sss.pgh.pa.us>
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.32.4 (3.32.4-1.fc30) 
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Precedence: bulk

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