Making the first few chapters of Part III more novice-friendly
Paul Weiss <[email protected]> Sat, 4 Jan 2020 10:13:54 +0000
| Newsgroups | gmane.comp.db.postgresql.devel.documentation |
|---|---|
| Message-ID | <MWHPR15MB1839C5C600A0EC37D9B04934DC220@MWHPR15MB1839.namprd15.prod.outlook.com> |
--_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<https://www.postgresql.org/docs/12/installatio=
n.html> 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
<html>
<head>
<meta http-equiv=3D"Content-Type" content=3D"text/html; charset=3Diso-8859-=
1">
<style type=3D"text/css" style=3D"display:none;"> P {margin-top:0;margin-bo=
ttom:0;} </style>
</head>
<body dir=3D"ltr">
<div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt;=
color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
<font size=3D"3">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?<br>
<br>
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
<a href=3D"https://www.postgresql.org/download/" style=3D"">https://www.pos=
tgresql.org/download/</a>. Or add those things to Section 1.1 in part I . I=
t says "If you are installing PostgreSQL yourself, then refer to
<a href=3D"https://www.postgresql.org/docs/12/installation.html" style=3D""=
>Chapter 16</a> for instructions on installation", but chapter 16 is o=
nly really about installation from source code.<br>
<br>
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
<a href=3D"https://www.postgresql.org/docs/12/install-windows.html" style=
=3D"">Chapter 17</a> 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.<br>
<br>
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.<br>
<br>
I am happy to help develop solutions for any of the comments I send out. </=
font><br>
</div>
<div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt;=
color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
<font size=3D"3"><br>
</font></div>
<div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt;=
color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
<font size=3D"3">Paul</font></div>
</body>
</html>
--_000_MWHPR15MB1839C5C600A0EC37D9B04934DC220MWHPR15MB1839namp_--