Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1iXpuk-0000Q5-4P for pgsql-docs@arkaria.postgresql.org; Thu, 21 Nov 2019 17:06:42 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1iXpui-0001pt-Te for pgsql-docs@arkaria.postgresql.org; Thu, 21 Nov 2019 17:06:40 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1iXpui-0001pl-J7 for pgsql-docs@lists.postgresql.org; Thu, 21 Nov 2019 17:06:40 +0000 Received: from mail-qt1-x82a.google.com ([2607:f8b0:4864:20::82a]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1iXpuf-0004Ka-Hp for pgsql-docs@lists.postgresql.org; Thu, 21 Nov 2019 17:06:40 +0000 Received: by mail-qt1-x82a.google.com with SMTP id 30so4440655qtz.12 for ; Thu, 21 Nov 2019 09:06:37 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=os+dtGSR+7xoT4ZDDDsOR7mPwgv06ENzP1R+lkwUL+k=; b=fPYAOboFljnNqkExBQUG/if4/BI2LCP9Zst6N+chiUot9jzqb5zW3yZ0Aa+UAWCteh uBumb16bpeeV0vf6DXjFsYPdiyLA9MIQeHhEa3pyUsakCeEBU19Pyd286s10a/vy97W0 9ZO54jF+bN6HPWXWQ/skFcXMweGpolJflNYpQNuhXxj0ChQUKpOgTPG4/2PlE4xhwGUv tCwhBdbjcAlhr+z3g2FjSsbTRg7X54Yof8bYB1e37h3d5+eIbebAXdS13YeFbKsCIM2R O8em9CJy1tdi8/5vpKVJgifvNFqpf1TZTh8SpVX0MfM0DrVYLIbDV9ZfdJ8BlUrphUJq UR2A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=os+dtGSR+7xoT4ZDDDsOR7mPwgv06ENzP1R+lkwUL+k=; b=rQzT7YJn9I03+cH0ti+cB+Q/EtChA3SjideQz8K0RmGB9ic/nveGKGGVm+NRkAVgpB Va0ZLWRk4gJSZ6eXhn4juYpj4HlX1NjPYIlmMm12IrOZtl/QdTrlGMR+2qy0ddLXH0NP 5qK1EZ0YIHwwd7ddnZmrxO1fsUiCxJa3aNvZKm5uWyDz+2uTjn+n+SMekIoP+TmZRKnR 0X2DPWg4Pu+GI3nsUPuGVka9xKsEt7Bv5ZDGyeWaeecX6un9+V/TjVeBI/lfJItrDDxT Op2sFbr/6Cra2X7wntCO0SRnTh8uGUrZYCt650kc5N9WYMh7vtoy3yL2NNetYxQ0rmRz MpZg== X-Gm-Message-State: APjAAAVZhXJwqItD4b1tlTfvH1j8icNoMRMq+cr0Faf/BAHDZpvP5h1D zZMvUNv87iH00DdUGtIxmCCQP2ztwro2nYb8hmY= X-Google-Smtp-Source: APXvYqyMDt+GXBV5UZh7UyaXM50Hp1UtNHRHp1bwOL5KClDdKBXYvml5ylZ9X75UE3VnJly4fIjOQ0H+Ghgc4r4RFIw= X-Received: by 2002:ac8:2c99:: with SMTP id 25mr4706149qtw.147.1574355995618; Thu, 21 Nov 2019 09:06:35 -0800 (PST) MIME-Version: 1.0 References: <54907b90aa20e603eb4204153c7dd5790ce258a4.camel@cybertec.at> <9058.1574179093@sss.pgh.pa.us> <2dd3a48be2f6b7b18631051b61e568fea98c10ec.camel@cybertec.at> <1864.1574262830@sss.pgh.pa.us> In-Reply-To: <1864.1574262830@sss.pgh.pa.us> From: Liudmila Mantrova Date: Thu, 21 Nov 2019 20:06:24 +0300 Message-ID: Subject: Re: GSoD - a patch for Getting Started tutorial To: Tom Lane Cc: Laurenz Albe , pgsql-docs@lists.postgresql.org, Stephen Frost , Sarah Conway Schnurr Content-Type: multipart/alternative; boundary="000000000000de7ea60597de51d8" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --000000000000de7ea60597de51d8 Content-Type: text/plain; charset="UTF-8" On Wed, Nov 20, 2019 at 6:13 PM Tom Lane wrote: > Laurenz Albe 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 --000000000000de7ea60597de51d8 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable

On Wed, Nov 20, 2019 at 6:13 PM Tom Lane = <tgl@sss.pgh.pa.us> wrote:
Laurenz Albe <= laurenz.albe@= cybertec.at> writes:
> I kind of like the "troubleshooting" section, but I am unsur= e where
> to set the limit.=C2=A0 What is there currently doesn't cover all<= br> > potential causes (e.g., connection via TCP, see Windows), but
> being exhaustive is probably impossible and not even desirable.
=C2=A0
Thank you for your feedback! I'll be gl= ad 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 fol= low the tutorial. As you've already mentioned, Windows is not covered r= ight now, so once I add it, I can add the Windows-specific connection issue= s too. However, if we cover Windows, I think it's logical to include P= GDG 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.=C2=A0 We could define such terms there, and
make the tutorial's uses of them be hyperlinks.=C2=A0 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 valua= ble. However, I have some doubts about including each and every computer-re= lated term -=C2=A0 should we keep it more DBMS-specific? As for the "a= bsolute 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 sur= e
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 pr= eference is to use it without a hyphen, but then we'd have to change th= e spelling everywhere in our docs.

--
Best regards,Liudmila Mantrova=C2=A0

Technical writer at Postg= res Professional: = http://www.postgrespro.com
--000000000000de7ea60597de51d8--