From: | Liudmila Mantrova <l(dot)mantrova(at)gmail(dot)com> |
---|---|
To: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> |
Cc: | Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>, pgsql-docs(at)lists(dot)postgresql(dot)org, Stephen Frost <sfrost(at)snowman(dot)net>, Sarah Conway Schnurr <xenophenes42(at)gmail(dot)com> |
Subject: | Re: GSoD - a patch for Getting Started tutorial |
Date: | 2019-11-21 17:06:24 |
Message-ID: | CAEkD-mBFQb61gHNWR0cN5K4G4q-i1PRwNn_OKVkKSaaJa5_LbA@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs |
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
From | Date | Subject | |
---|---|---|---|
Next Message | PG Doc comments form | 2019-11-21 20:06:28 | documentation clarifications for "alter sequence" ? |
Previous Message | Tatsuo Ishii | 2019-11-21 07:43:39 | Re: standalone-install.xml |