On Sep 13, 2007, at 12:58 AM, Greg Smith 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.
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. 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.
Isn't that the point of the documentation? I mean, if the existing,
official manual has been demonstrated (through countless mailing list
help requests) to not sufficiently explain a given topic, shouldn't
it be revised? One thing that might help is a hyperlinked glossary
so that people reading through the documentation can go straight to
the postgres definition of dead tuple, index bloat, etc.
Erik Jones
Software Developer | Emma®
erik@xxxxxxxxxx
800.595.4401 or 615.292.5888
615.292.0777 (fax)
Emma helps organizations everywhere communicate & market in style.
Visit us online at http://www.myemma.com
---------------------------(end of broadcast)---------------------------
TIP 7: You can help support the PostgreSQL project by donating at
http://www.postgresql.org/about/donate
