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