Making the first few chapters of Part III more novice-friendly
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 novice-friendly?
For example, consider adding a brief chapter before chapter 16 on installation in general, explaining the options in general, the pros and cons of each, 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 yourself, then refer to Chapter 16<https://www.postgresql.org/docs/12/installation.html> for instructions on installation", but chapter 16 is only really about installation from source code.
The intro to chapter 16 also states "If you are building PostgreSQL for 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++, 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 knowing about the much-easier-to-install binary version. Another example is at the top 18.1. It would be nice to have a brief explanation what a server daemon is, or if nothing else, a link to the Wikipedia article.
It would be great to make these chapters more friendly to PostgreSQL novices who are Windows users. Windows (for non-developers) doesn't use the concept 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 Mac users do not know it is based on UNIX). In the first paragraph of 18.2 talks about initializing a storage area, but "initializing" is not a term regularly used by Windows users. In the third sentence of the second paragraph it would be helpful to either add a Windows example, or at least say something 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 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
On Sat, Jan 4, 2020 at 10:13:54AM +0000, Paul Weiss wrote:
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
novice-friendly?For example, consider adding a brief chapter before chapter 16 on installation
in general, explaining the options in general, the pros and cons of each, 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 yourself, then refer
to Chapter 16 for instructions on installation", but chapter 16 is only really
about installation from source code.The intro to chapter 16 also states "If you are building PostgreSQL for
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++, see Chapter 17
instead." A novice might infer from that that those are the only 2 options,
rather than knowing about the much-easier-to-install binary version. Another
example is at the top 18.1. It would be nice to have a brief explanation what a
server daemon is, or if nothing else, a link to the Wikipedia article.It would be great to make these chapters more friendly to PostgreSQL novices
who are Windows users. Windows (for non-developers) doesn't use the concept 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 Mac users do not
know it is based on UNIX). In the first paragraph of 18.2 talks about
initializing a storage area, but "initializing" is not a term regularly used by
Windows users. In the third sentence of the second paragraph it would be
helpful to either add a Windows example, or at least say something 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 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.
There is no question that our tutorials and novice stuff is lacking. We
are very good with reference material.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +