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