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 1ingRW-0000NW-DD for pgsql-docs@arkaria.postgresql.org; Sat, 04 Jan 2020 10:14:02 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1ingRV-0002T8-4u for pgsql-docs@arkaria.postgresql.org; Sat, 04 Jan 2020 10:14:01 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1ingRU-0002T1-Pc for pgsql-docs@lists.postgresql.org; Sat, 04 Jan 2020 10:14:00 +0000 Received: from mail-dm6nam10olkn2024.outbound.protection.outlook.com ([40.92.41.24] helo=NAM10-DM6-obe.outbound.protection.outlook.com) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ingRQ-0006uQ-RE for pgsql-docs@lists.postgresql.org; Sat, 04 Jan 2020 10:13:59 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=j/zmKtOOQ7H8xbZ25pRdfrsjgmndDgjozud8xD/TeJ5qg5vtwC4Eb5ZRamRhNYDq7BjzwCB5Ct5P+23p4qvZO5HT73hTidPpeEqyMW9Q/7T2xmt3hJz8ZWC/NN+hshte/L28F1+IlouslQOsbbQFZW//oIMOT6yNnZg0dB/C75Y1mUS3muGAhYy09hqsUf8OLasLmP15kku/x5ry+sNxyFPSSJDTGohzAXFW1NT6FtX25duQLPMAlZ85rhSIP4MEShy5Guq4wyb0G3JjDp8MKGE+TuznaML2VA/gskTaoRFyGB0gVIMX5Yy5PUfeFf6ujmPbxr1/emVMEhHJ/bwQ+Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=KHlsBe073BBoY0ulBCmL+aYg7S4E9ntFwJcKW74utjM=; b=C6LFjrZJVZNYJBjY3/FjdDUJFad3dgsC0SQOSia0Gymp8bC3v8T1R4jVQdF2Sv1lzarHfj6iiIeBuXTk6lB0KQceK3VdEkGJHyxkxdU+gdi2Ck0PXfGfzB9fjDiEfQksiaxEZC7l4eVeQD8GG4GMsgXmXHeU79VmLLg8aJuZsPD4tdoLr7Kkg63+NsCjG9rQGa/7rO+0lLtBzq90T+o5wjScvp3TrWP7eI79++nHqcF7i1WMW9R2C2n0qf47nT0X5pDyYEE/RzIdvH1Awcl9VGxakdnOWOA35ffxXge+TwG351p4T6sz+CEdnWlRBBTBI0k+PgyeHojedqVYyMzjfw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=hotmail.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=KHlsBe073BBoY0ulBCmL+aYg7S4E9ntFwJcKW74utjM=; b=f47MgVqXxDmoN1NAqfjytXGrf7vHyeR+m8dtNGUz2GiicAPbzSuYLCdmWnLxF2l2u4PaNO9ph1x5x/ERRSX2/n0SoSo2M1ViKptgqLmETx4YZZzyp6M2OqLQdoJ+7NolsYKQKFHV9QK2TS0L1ubW16mgjakyvJsTAZ9O7kTgddaWc60GkAQM1cWjn0VCHcqpSZmXcJTz1xhxtttCu+Mt2NIPpoT5kOodeI5U886iPcM0zDGKeVA0miV/DM0k/WsEXTLJk8bJw/CZWDVpI1oOlSTLzNM8kCPUnjgrMYSOW5xRs/ODvFtvh8+OirmCXcm1C5/J8P2PemUxAihwiNx22g== Received: from DM6NAM10FT019.eop-nam10.prod.protection.outlook.com (10.13.152.51) by DM6NAM10HT206.eop-nam10.prod.protection.outlook.com (10.13.153.181) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2602.11; Sat, 4 Jan 2020 10:13:54 +0000 Received: from MWHPR15MB1839.namprd15.prod.outlook.com (10.13.152.59) by DM6NAM10FT019.mail.protection.outlook.com (10.13.152.96) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2602.11 via Frontend Transport; Sat, 4 Jan 2020 10:13:54 +0000 Received: from MWHPR15MB1839.namprd15.prod.outlook.com ([fe80::6c84:ae5c:f808:75ad]) by MWHPR15MB1839.namprd15.prod.outlook.com ([fe80::6c84:ae5c:f808:75ad%12]) with mapi id 15.20.2602.012; Sat, 4 Jan 2020 10:13:54 +0000 From: Paul Weiss To: "pgsql-docs@lists.postgresql.org" Subject: Making the first few chapters of Part III more novice-friendly Thread-Topic: Making the first few chapters of Part III more novice-friendly Thread-Index: AQHVwueWZLUlMtc1CkuEdNMKhICLFA== Date: Sat, 4 Jan 2020 10:13:54 +0000 Message-ID: Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-incomingtopheadermarker: OriginalChecksum:145C3F3E63C9581A6AA12E54FC1D51A8A66151029FA6EFC45D62ECAA383587B3;UpperCasedChecksum:F8F5E9B5871443C9EAEDC1DB0EB0E1702BDAD5E492A40112BA855EF810DCA3C5;SizeAsReceived:6783;Count:42 x-tmn: [wfyKCB5ZCNvk6jLtXZ5oDRi+Aazc9ERJw2wIOfzgjyA=] x-ms-publictraffictype: Email x-incomingheadercount: 42 x-eopattributedmessage: 0 x-ms-office365-filtering-correlation-id: b4646d10-95d3-4003-ff6c-08d790fecdfa x-ms-traffictypediagnostic: DM6NAM10HT206: x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: iPXNk2+eb5ObTnt7aY1WrcSkjijqpADHhNpUHl+fOh+WqU+RvH6g3DIIg7K21kcSHuP86obScbX++ChpvISO4k8kcfO2FRU33dRaqGGsojNk9UZQ7YxSSw2wwlRofD8xmVl94z2iZPCEo4iGFSbisatEys6i9hY1FTARmOF9yFM6oRGIfJGdvd9GqUEo6iJDyZIV04Lrq4NkhqUaoFuwPVUhjIj/SlBaysTXPK6dcpY= x-ms-exchange-transport-forked: True Content-Type: multipart/alternative; boundary="_000_MWHPR15MB1839C5C600A0EC37D9B04934DC220MWHPR15MB1839namp_" MIME-Version: 1.0 X-OriginatorOrg: hotmail.com X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-CrossTenant-Network-Message-Id: b4646d10-95d3-4003-ff6c-08d790fecdfa X-MS-Exchange-CrossTenant-rms-persistedconsumerorg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-CrossTenant-originalarrivaltime: 04 Jan 2020 10:13:54.7796 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Internet X-MS-Exchange-CrossTenant-id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6NAM10HT206 List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --_000_MWHPR15MB1839C5C600A0EC37D9B04934DC220MWHPR15MB1839namp_ Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable The intro to Part III says "The first few chapters are written so they can = be understood without prerequisite knowledge, so new users who need to set = up their own server can begin their exploration with this part." With that = in mind, could chapters on installation and chapters 18 & 19 be made more n= ovice-friendly? For example, consider adding a brief chapter before chapter 16 on installat= ion in general, explaining the options in general, the pros and cons of eac= h, and a link to https://www.postgresql.org/download/. Or add those things = to Section 1.1 in part I . It says "If you are installing PostgreSQL yourse= lf, then refer to Chapter 16 for instructions on installation", but chapter 16 is only really ab= out installation from source code. The intro to chapter 16 also states "If you are building PostgreSQL for Mic= rosoft Windows, read this chapter if you intend to build with MinGW or Cygw= in; but if you intend to build with Microsoft's Visual C++, see Chapter 17<= https://www.postgresql.org/docs/12/install-windows.html> instead." A novice= might infer from that that those are the only 2 options, rather than knowi= ng about the much-easier-to-install binary version. Another example is at t= he top 18.1. It would be nice to have a brief explanation what a server dae= mon is, or if nothing else, a link to the Wikipedia article. It would be great to make these chapters more friendly to PostgreSQL novice= s who are Windows users. Windows (for non-developers) doesn't use the conce= pt of file ownership, and uses "user account" differently, so explanations = of those would be helpful. The second paragraph begins "To add a Unix user = account to your system", but nothing about Windows or macOS (I think many M= ac users do not know it is based on UNIX). In the first paragraph of 18.2 t= alks about initializing a storage area, but "initializing" is not a term re= gularly used by Windows users. In the third sentence of the second paragrap= h it would be helpful to either add a Windows example, or at least say some= thing like "There is no default, although in UNIX popular locations include= /usr/local/pgsql/data and /var/lib/pgsql/data." (Related, it would also be= nice in section 3 of the preface to note that most commands in the manual = are given in UNIX, and that in Windows you would use backslashes rather tha= n forward slashes in, for example, path names.) While 18.3 has specific con= tent for 5 UNIX varieties, there is no specific content for Windows. I am happy to help develop solutions for any of the comments I send out. Paul --_000_MWHPR15MB1839C5C600A0EC37D9B04934DC220MWHPR15MB1839namp_ Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable
The intro to Part III says "The first few chapters ar= e written so they can be understood without prerequisite knowledge, so new = users who need to set up their own server can begin their exploration with = this part." With that in mind, could chapters on installation and chapters 18 & 19 be made more novice-friendly?

For example, consider adding a brief chapter before chapter 16 on installat= ion in general, explaining the options in general, the pros and cons of eac= h, and a link to https://www.pos= tgresql.org/download/. Or add those things to Section 1.1 in part I . I= t says "If you are installing PostgreSQL yourself, then refer to Chapter 16 for instructions on installation", but chapter 16 is o= nly really about installation from source code.

The intro to chapter 16 also states "If you are building PostgreSQL fo= r Microsoft Windows, read this chapter if you intend to build with MinGW or= Cygwin; but if you intend to build with Microsoft's Visual C++, se= e Chapter 17 instead." A novice might infer from that that tho= se are the only 2 options, rather than knowing about the much-easier-to-ins= tall binary version. Another example is at the top 18.1. It would be nice to have a brief explanation what a server d= aemon is, or if nothing else, a link to the Wikipedia article.

It would be great to make these chapters more friendly to PostgreSQL novice= s who are Windows users. Windows (for non-developers) doesn't use the conce= pt of file ownership, and uses "user account" differently, so exp= lanations of those would be helpful. The second paragraph begins "To add a Unix user account to your system", bu= t nothing about Windows or macOS (I think many Mac users do not know it is = based on UNIX). In the first paragraph of 18.2 talks about initializing a s= torage area, but "initializing" is not a term regularly used by Windows users. In the third sentence of the second parag= raph it would be helpful to either add a Windows example, or at least say s= omething like "There is no default, although in UNIX popular locations= include /usr/local/pgsql/data and /var/lib/pgsql/data." (Related, it would also be nice in section 3 of the preface to note that m= ost commands in the manual are given in UNIX, and that in Windows you would= use backslashes rather than forward slashes in, for example, path names.) = While 18.3 has specific content for 5 UNIX varieties, there is no specific content for Windows.

I am happy to help develop solutions for any of the comments I send out.

Paul
--_000_MWHPR15MB1839C5C600A0EC37D9B04934DC220MWHPR15MB1839namp_--