DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=beta;
	h=received:subject:from:reply-to:to:in-reply-to:references:content-type:date:message-id:mime-version:x-mailer:content-transfer-encoding;
	b=G9j0D/2eAZ7/uU1fE8pw38uOm679fde8Kn2l7muoY/rrYxxKm43pMrFbrHGZRVwGkOv7/iLw2gJi8+nZvZuRwqmCPIvGGI9SqLUXjCkppG677KGVV/+y9BYhd60IsTF5oUX+GGZK5dabla/culU4w+7KZ3jYHXZo4B63PNcZNq4=
Subject: Re: [Again] Postgres performance problem
From: Adam Tauno Williams <adamtaunowilliams@gmail.com>
Reply-To: adamtaunowilliams@gmail.com
To: pgsql-performance@postgresql.org
In-Reply-To: <dcc563d10709130939w1428f5d1uf56faa615e212362@mail.gmail.com>
References: <46E636CB.8080008@rentalia.com>
	<43393.192.121.104.48.1189495883.squirrel@zigo.dhs.org>
	<46E64891.9080005@rentalia.com> <20070911225242.GG38801@decibel.org>
	<46E79865.906@rentalia.com>
	<dcc563d10709121128o1e5883a9n96b1f9ed74901be9@mail.gmail.com>
	<Pine.GSO.4.64.0709130130390.8547@westnet.com>
	<81405E66-5110-4DA8-B315-D28EA124CDB6@myemma.com>
	<dcc563d10709130939w1428f5d1uf56faa615e212362@mail.gmail.com>
Content-Type: text/plain
Date: Fri, 14 Sep 2007 10:00:59 -0400
Message-Id: <1189778459.5199.5.camel@aleph.wmmi.net>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

> > 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? 

Or it proves that no one bothers to read the docs.

> > 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.
> Yes and no.  The official docs are more of a technical specification.
> Short, simple and to the point so that if you know mostly what you're
> doing you don't have to wade through a long tutorial to find the
> answer.  I find MySQL's documentation frustrating as hell because I
> can never find just the one thing I wanna look for.

Yes!  MySQL documentation is maddening.

This is why, I suspect, for products like Informix and DB2 IBM publishes
two manuals (or roughly equivalent to two manuals):  a "guide" and a
"reference".

> written as a tutorial.  I.e. I have to pay the "stupid tax" when I
> read their docs.

Yep.

> What I want to do is two fold.  1: fix the technical docs so they have
> better explanations of each of the topics, without turning them into
> huge tutorials.  2:  Write a vacuuming tutorial that will be useful
> should someone be new to postgresql and need to set up their system.
> I think the tutorial should be broken into at least two sections, a
> quick start guide and an ongoing maintenance and tuning section.