Tom Lane wrote:
> "Jonah H. Harris" <jonah.harris@gmail.com> writes:
>> On Feb 5, 2008 11:54 PM, Decibel! <decibel@decibel.org> wrote:
>>> One of the things that drew me to Postgres years ago was that I could
>>> actually read about how it works in a clear, concise manner.
>
>> Agreed.
>
> Not sure how you could argue "concise" as a benefit here.
>
> There are literally thousands of aspects of the PG codebase that could
> impact performance in user-visible ways. Most of them are not
> documented in the SGML docs. If we tried to expose all that, the docs
> would become completely unreadable. (I just got done reading some
> slashdot griping about how our docs are already too long and too
> complicated for novices, so I'm not feeling particularly charitable
> about proposals to dump even more seldom-useful details into them.)
>
That's something we hear on booths too. Someone, at Solutions Linux
2008, told me the manual is great but not that easy to begin with. He
reads Sébastien Lardière's french book on PostgreSQL and finds it more
convenient for him. And now he needs something more advanced but still
not the manual... problem is, he's not able to explain why he doesn't
like our current manual.
> I'm really not seeing the case for user-level documentation of HOT,
> when for instance most of the planner's optimization behavior is not
> so documented.
>
A user level, no. But an advanced/developper level documentation would
be greatly appreciated.
Really, I found our manual great. I've read it many times, I've
translated it, I think I know it a bit. But I think a 1500 pages manual
is a bit too much for a beginner. It kind of afraids them. And it may
not be enough for advanced users. Drawing the line between not enough
and too much is not that easy. But I'm sure there's work to do on the
documentation front.
Regards.
--
Guillaume.
http://www.postgresqlfr.org
http://dalibo.com