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: <20060119220041.GG78403@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>
	<1137687319.25500.129.camel@state.g2switchworks.com>
	<20060119220041.GG78403@pervasive.com>
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
Message-Id: <1137711094.25500.152.camel@state.g2switchworks.com>
Mime-Version: 1.0
Date: Thu, 19 Jan 2006 16:51:34 -0600

On Thu, 2006-01-19 at 16:00, Jim C. Nasby wrote:
> On Thu, Jan 19, 2006 at 10:15:19AM -0600, Scott Marlowe wrote:
> > I agree completely.  We don't probably need it in sgml just yet.  From a
> 
> Actually, I was looking for how to get the view out of the existing SGML
> ;) In any case, I think admin is probably broad enough that there won't
> be much overlap with other sections.
> 
> > 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)
> 
> Should probably mention contrib in here somewhere... and other
> resources, like pgFoundry. Afterall, the install section is somewhat of
> someone's introduction to PostgreSQL...

Good point.  I'll add that somewhere in there under software
installation.

> > - Management
> > -- Databases
> > -- Users
> > -- Roles and Privileges
> 
> Somewhere in one or both of the above should probably be some discussion
> on security practices... Also, pg_hba.conf is a bit of a stickler,
> because it is closely related to users and authentication.
> postgresql.conf is also a bit tricky, because many of it's settings
> require knowledge from other areas. Maybe the best way to deal with
> these is extensive cross-linking? IE: each postgresql.conf item (or set
> of items) should have a link back to whatever section explains it in
> detail.

Yeah, I keep thinking more and more we need a LOT of linkable resources
for this, much like the ones we have for all the standard command
reference stuff.  I'm leaning towards having the main page of each of
these things be somewhat closer to an executive summary (not that light
on info, but you know what I mean) and have links to more info for each
subject.  So that each section can have a much more in depth coverage
but not make it a huge slog to get through the documentation.