On 9/13/07, Greg Smith <gsmith@xxxxxxxxxxxxx> 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... ---------------------------(end of broadcast)--------------------------- TIP 6: explain analyze is your friend
