Re: Making the first few chapters of Part III more novice-friendly - Mailing list pgsql-docs

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 +