On 9/13/07, Greg Smith <gsmith@gregsmith.com> wrote:
> On Wed, 12 Sep 2007, Scott Marlowe wrote:
>
> > I'm getting more and more motivated to rewrite the vacuum docs. I think
> > a rewrite from the ground up might be best... I keep seeing people
> > doing vacuum full on this list and I'm thinking it's as much because of
> > the way the docs represent vacuum full as anything.
>
> I agree you shouldn't start thinking in terms of how to fix the existing
> documentation. I'd suggest instead writing a tutorial leading someone
> through what they need to know about their tables first and then going
> into how vacuum works based on that data.
I think both things are needed actually. The current docs were
started back when pg 7.2 roamed the land, and they've been updated a
bit at a time. The technical definitions of vacuum, vacuum full,
analyze etc all show a bit too much history from back in the day, and
are confusing. so, I think that 1: vacuum and analyze should have
their own sections. analyze used to be a subcommand of vacuum but it
no longer is, but the docs still pretty much tie them together. 2:
The definition for vacuum full needs to include a caveat that vacuum
full should be considered more of a recovery operation than a way to
simply get back some space on your hard drives.
Which leads me to thinking that we then need a simple tutorial on
vacuuming to include the free space map, vacuum, vacuum analyze,
vacuum full, and the autovacuum daemon. We can throw analyze in there
somewhere too, I just don't want it to seem like it's still married to
vacuum.
> As an example, people throw around terms like "index bloat" and "dead
> tuples" when talking about vacuuming. The tutorial I'd like to see
> somebody write would start by explaining those terms and showing how to
> measure them--preferably with a good and bad example to contrast.
I agree. I might rearrange it a bit but that's the way I'm looking at it too.
> The way
> these terms are thrown around right now, I don't expect newcomers to
> understand either the documentation or the advice people are giving them;
> I think it's shooting over their heads and what's needed are some
> walkthroughs. Another example I'd like to see thrown in there is what it
> looks like when you don't have enough FSM slots.
OK. Got something to start with. I'm thinking I might work on a
vacuum tutorial first, then the tech docs...