Skip site navigation (1) Skip section navigation (2)

Thoughts about the installation instructions

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: <pgsql-docs(at)postgresql(dot)org>
Subject: Thoughts about the installation instructions
Date: 2002-03-11 21:53:02
Message-ID: Pine.LNX.4.30.0203111632000.690-100000@peter.localdomain (view raw or flat)
Thread:
Lists: pgsql-docs
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(at)gmx(dot)net


Responses

pgsql-docs by date

Next:From: Thomas LockhartDate: 2002-03-11 22:04:37
Subject: Re: Thoughts about the installation instructions
Previous:From: Peter EisentrautDate: 2002-03-11 05:14:02
Subject: Re: pagination in the PostgreSQL 7.2 Programmer's Guide

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group