Re: GSoD - a patch for Getting Started tutorial

On Wed, Nov 20, 2019 at 6:13 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)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.
>

Thank you for your feedback! I'll be glad even if some part of this patch
improves the getting started experience for novice users, so I can focus on
the install and troubleshooting first. I would limit troubleshooting to
those issues that might appear when we follow the tutorial. As you've
already mentioned, Windows is not covered right now, so once I add it, I
can add the Windows-specific connection issues too. However, if we cover
Windows, I think it's logical to include PGDG Linux packages as well.

>
> > 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?
>

I agree that having links to a glossary can be quite valuable. However, I
have some doubts about including each and every computer-related term -
should we keep it more DBMS-specific? As for the "absolute path" in
particular, I hope the example that follows clarifies things.

> > (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.
>

Right, I've been following the spelling that seems to be widely used in
documentation. My preference is to use it without a hyphen, but then we'd
have to change the spelling everywhere in our docs.

--
Best regards,
Liudmila Mantrova

Technical writer at Postgres Professional: http://www.postgrespro.com