Subject: Current docs are too comlicated for new Postgre users; thoughts on improvement

From: "Nikolay Samokhvalov" <[email-masked]>
Date: Thu, 25 Dec 2008 10:57:51 +0200

Currently, Part III (Server Administration) starts with three chapters:
  15. Installation Instructions
  16. Installation on Windows
  17. Operating System Environment

Here in Russia we have a situation, when the number of Win32 users of
Postgres is constantly increasing, so more and more questions like
"I've tried to install Postgres, clicked next/next/ok/ok/finish in
installation wizard, but it doesn't work / service cannot start / I
cannot connect" appear.

The problem is that we cannot just say "RTFM" them, because it's
really hard to find (and in some cases even impossible) to find the
proper part of docs. Why? The chapters 15 and 16 of the main docs are
not about installation -- they are about building Postgres from
sources. Currently, even for *nix DBA installation most frequently
means really installation from RPM/.deb/bsd ports/etc, including
creation of system user and running initdb.

As for Windows users, I haven't meet at least one who needs to know
how to build Postgres from sources under Windows! And really often I
see that Windows users cannot continue after some silly errors with
initdb process. Docs cannot help them -- they open Chapter 16, got
stuck and go away. And only really experienced DBAs know, that initdb
(one of the most important processes for newbies) is described in
"17.2. Creating a Database Cluster", which is located under "17.
Operating System Environment" in the main contents listing.

I think that docs really need to be clarified, at least titles should
be corrected. I'd rename chapter 15 to smth like 'Building from source
code on *nix platforms", and 16th one to 'Building from source code on
Windows' and chapter 17 (most important) to 'Creation and Initial
configuration of database cluster' (maybe with some corrections of
contents).

Going further, I'd remove detailed building instructions from the
beginning of Server Administration part (either to separate but single
chapter or even to appendix) and describe in details how to install
Postgres in different ways on different platforms, including:
 - installation from RPM/deb/other packages;
 - special attention to Windows users (how to install? what are common
problems?) /* btw, I won't wonder if win32 version of Postgres is
being downloaded more often than others */
 - short version of installation from sources;
 - initdb process;
 - initial configuration on different platforms.

I believe that this question is one of the most important when we are
thinking how to grow user base.

Thoughts?

-- 
Sincerely yours,
Nikolay Samokhvalov
Postgresmen LLC, http://postgresmen.ru

---

From: "Виктор Вислобоков" <[email-masked]>
Date: Thu, 25 Dec 2008 12:32:48 +0300

Hello All.

I agree with Nikolay. Windows users run into the problems during
installation very often.
They ask questions about these problems again and again at the forums. In
some cases, I don't know that I can answer, because some problems is hard to
my mind.

With best wishes,
Victor Vislobokov
St.Peterburg, Russia

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 09 Jan 2009 15:37:17 +0200

> configuration of database cluster' (maybe with some corrections of

Changed to:

III. Server Administration
15. Installation from Source Code
16. Installation from Source Code on Windows
17. Server Setup and Operation

>  - installation from RPM/deb/other packages;

Well, we can only describe what we ship.  It is up to those packages to 
adequately describe what they are doing.

---

From: "Emanuel Calvo Franco" <[email-masked]>
Date: Fri, 9 Jan 2009 12:13:02 -0200

> Operating System Environment" in the main contents listing.

Here in Argentina is happenning the same thing.
In that way we create content in our site (arpug.com.ar) .
Wherever, there is a wiki, and there is a lot of that information on the web.
But, you are correct when you talk about troubleshooting problems
on windows and in the mailing list some people answer when a guy
have windows problems 'migrate to *nix'...

> configuration of database cluster' (maybe with some corrections of
in the same site we expose tis howto because the only place that exist
is in the wiki

> thinking how to grow user base.

I'm watching that the manual in pdf is growing and my poor computer cries
when i open 8.4devel manual.. i don't think when we arrive to 8.5...

> Sent via pgsql-docs mailing list ([email-masked])
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs
>

-- 
      Emanuel Calvo Franco
   ArPUG / AOSUG Member
 Postgresql Support & Admin

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 9 Jan 2009 09:45:36 -0500 (EST)

Peter has made a change to improve this:

---------------------------------------------------------------------------

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 12 Jan 2009 17:09:10 +0200

> 	17. Server Setup and Operation

That is what I said ...