Thread: 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 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.
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.
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 +