Message-ID: <395B8DB5.6C062013@alumni.caltech.edu>
Date: Thu, 29 Jun 2000 17:56:05 +0000
From: Thomas Lockhart <lockhart@alumni.caltech.edu>
Organization: Yes
MIME-Version: 1.0
To: Peter Eisentraut <peter_e@gmx.net>
Cc: pgsql-docs@postgresql.org
Subject: Re: Documentation organization
References: <Pine.LNX.4.21.0006291616400.397-100000@localhost.localdomain>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

> Comments? Suggestions? Better ideas?

I can't argue with the statement that the overall organization is about
right. :)

I'm not sure how "set" will differ from "part" when it comes time to
split up the hardcopy, but it might be pretty easy (it partly depends on
how the RTF assigns the styles). Do you want to try to do
"postgres.sgml" as a set-based doc and see how it works? Or modify it
and commit it as postgres-set.sgml so we can carry along both until the
kinks are worked out?

> Reference pages should be placed at the end of each document that they 
> fit into. E.g., postmaster in Administorator's guide, psql in 
> Interfaces, etc.

Hmm. I think that this might be OK, but I'm worried that there will be
some "grey area" categories that make it hard to figure out which doc to
look in for the reference. psql is a good example: why should it be in
"Interfaces" (coding interfaces?) instead of "Applications"?

But we can also carry along a separate "references" document which
*does* integrate them all, as well as including them at the end of each
relevant doc. I'm pretty sure that if I had to choose one or the other
I'd choose to put them together.

                  - Thomas