Subject: Re: vacuum and routine maintenance docs
From: Scott Marlowe <smarlowe@g2switchworks.com>
To: "Jim C. Nasby" <jnasby@pervasive.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, pgsql-docs@postgresql.org
In-Reply-To: <20060119013134.GR17896@pervasive.com>
References: <1137518049.25500.27.camel@state.g2switchworks.com>
	<20060117224941.GI17896@pervasive.com>
	<1137538769.25500.49.camel@state.g2switchworks.com>
	<20060118221951.GT17896@pervasive.com>
	<1137626008.25500.90.camel@state.g2switchworks.com>
	<5713.1137632107@sss.pgh.pa.us> <20060119011422.GM17896@pervasive.com>
	<5896.1137633556@sss.pgh.pa.us> <20060119013134.GR17896@pervasive.com>
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
Message-Id: <1137687319.25500.129.camel@state.g2switchworks.com>
Mime-Version: 1.0
Date: Thu, 19 Jan 2006 10:15:19 -0600

On Wed, 2006-01-18 at 19:31, Jim C. Nasby wrote:
> On Wed, Jan 18, 2006 at 08:19:16PM -0500, Tom Lane wrote:
> > "Jim C. Nasby" <jnasby@pervasive.com> writes:
> > > I'm wondering if people feel this is an issue with the docs in general
> > > and isn't limited to just the admin stuff?
> > 
> > Probably, but the admin stuff seems to suffer worst.  In any case, Scott
> > volunteered to look at redoing that part, and I'm not going to repay the
> > offer by asking him to redo the whole manual ;-)
> 
> Certainly true. :) But if we're going to start at an outline level I
> think it would be enlightening to do a short (as in only 2 levels deep)
> re-outline of all the docs and see how it compares to what we have. It
> would at least indicate things that should be wholesale moved out of the
> admin section...
> 
> Plus hopefully we could get others to help. :) I'd certainly lend a
> hand.
> 
> Is there an easy way to get a 2-level outline out of the sgml?

I agree completely.  We don't probably need it in sgml just yet.  From a
40,000 ft perspective, we can break administration up into several large
chunks, and then decide what needs to go in each.  The general "big
topics" we already have seem pretty serviceable.  However, I tend to
think of OS env and server config as being sub topics under
installation.  Under that, we can put the individual subjects
accordingly.

- Installation
-- Documentation scope specification
-- Preparation (setting objectives for the installation)
-- Hardware considerations (emphasizing things like fsyncing and all)
-- OS configuration (i.e. shared memory)
-- Software installation (source versus rpm versus pkg etc.)
-- Cluster initialization (localization issues, location, etc...)
-- Server configuration (i.e. pg_hba / postgresql.conf et. al.)
-- Running the server (start up scripts, by hand, etc.)
-- Verifying server operation (regression tests)

- Management
-- Databases
-- Users
-- Roles and Privileges

- Maintenance
-- Backup and Restore
-- PITR
-- Replication (where to look for it.)
-- Monitoring
-- Routine Maintenance (vacuum, analyze, etc...)

- Troubleshooting
 (I'm not sure what to put under here right now...  Will think on it.)

Please, feel free to rip this up and reassemble as necessary.  But I do
think it's important to regroup our subjects under a few very broad
topics.