Thread: Thoughts about the installation instructions

There are quite a few pieces of documentation that logically belong into
the installation instructions but are currently found elsewhere.  For
instance in the ODBC and JDBC chapters, in the chapter on client
authentication (pieces about Kerberos), the pecularities of installing
PL/{Perl,Python}, and basically any place that mentions "configure".

It is my view that there should be a clean separation between installation
and use documentation.  First of all, it's really useless to put
installation info into usage documentation because users see it too late.
Secondly, running "configure; make; make install" is really just one
several ways of installing PostgreSQL.  Users of packages don't care about
what options you have to pass to "configure" to get at a certain feature.
(There should be some well-defined and documented way of figuring out
whether a certain build-time option was activated, but that could be as
easy as checking whether certain files exist in the installed set.)

I define the installation to have completed after "make install" finishes.
This is how it currently is defined, too.  Running initdb is a grey area
because many packages handle it in different ways.  Clearly once you start
the postmaster you are in "usage" time.

So what I would like to strive for is this:

From any part of the documentation except the installation instructions,
remove any parts that mention configure options, build-time options,
build-time prerequisites, and the like.  Move those parts into the
installation instructions.  In some passages, insert something like "To
check whether <feature> is available at your site, look for a file <name>.
If it is missing, refer to the installation instructions."  (Here,
"installation instructions" may even refer to the instructions your vendor
may have provided for its package set.)

Furthermore, remove the chapter(s) on installation from the Admin Guide
and make then a document of their own.  This document need only exist in
the source tree and does not need to be installed.

Comments?

--
Peter Eisentraut   peter_e@gmx.net

> Furthermore, remove the chapter(s) on installation from the Admin Guide
> and make then a document of their own.  This document need only exist in
> the source tree and does not need to be installed.
>
> Comments?

Makes sense.  I assume the other stuff was just placed close to the
topic, like JDBC install near the JDBC chapter.  Moving it into install
seems OK too.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Peter Eisentraut <peter_e@gmx.net> writes:
> It is my view that there should be a clean separation between installation
> and use documentation.  First of all, it's really useless to put
> installation info into usage documentation because users see it too late.

This is too rigid a worldview.

The point of mentioning configuration issues in the usage docs is
that usage is when people will *find out* that they misconfigured
something.  A link letting them know what they need to fix when they
observe some particular problem is not out of place in the usage docs.

I do agree that the installation procedures should mention all these
issues, too.  Just don't strip out the references in the usage docs.

> Furthermore, remove the chapter(s) on installation from the Admin Guide
> and make then a document of their own.  This document need only exist in
> the source tree and does not need to be installed.

Mumble.  Certainly this could be a separate "book", but I strongly
disagree with removing it from the standard documentation set.  To
my mind, the "integrated doc" *is* the standard documentation set and
should contain everything.

            regards, tom lane

Tom Lane writes:

> The point of mentioning configuration issues in the usage docs is
> that usage is when people will *find out* that they misconfigured
> something.  A link letting them know what they need to fix when they
> observe some particular problem is not out of place in the usage docs.

Yes, a link to the installation instructions is exactly what I'm
suggesting.  Clearly these things belong into the installation
instructions at least.  But I don't want to repeat the entire spiel about
the shared libperl everywhere PL/Perl is mentioned.  Just say, if you
don't have have it, look into the installation instructions.

> Mumble.  Certainly this could be a separate "book", but I strongly
> disagree with removing it from the standard documentation set.  To
> my mind, the "integrated doc" *is* the standard documentation set and
> should contain everything.

OK.

--
Peter Eisentraut   peter_e@gmx.net

...
> Furthermore, remove the chapter(s) on installation from the Admin Guide
> and make then a document of their own.  This document need only exist in
> the source tree and does not need to be installed.
> Comments?

All good ideas. One small nit: the Installation Guide should be part of
the built-and-installed doc set, always. I know that sometimes (maybe
most times) folks reading it will be sitting in front of a clean machine
with a tarball and a beer, but in other cases folks will be sitting in
front of an RPM-installed machine wondering how to do a from-source
build for their next project. No need to make the docs harder to find
and read than necessary.

                    - Thomas