On Feb 4, 2009, at 9:33 AM, Robert Haas wrote:
> Just to play devil's advocate, I have used the PostgreSQL
> documentation for years and have long understood that the references
> pages are the place to go if you really need the nitty-gritty on how a
> particular command works. I agree that you might not realize this if
> you just casually Google your way in, but I can't imagine that problem
> is fixable. You'll just end up with a zillion cross-references that
> will, overall, reduce the clarity and readability of the
> documentation, which is overall very good.
I think that all pages that seem to document particular features
should cross-reference the reference pages in section VI, but not
necessarily vice-versa. I don't think that's asking for a lot. If
you're reading the narrative section, um, narratively, then you'll see
lots of "Look here for more on this topic when you're ready," and that
will be much more useful for the search-result-hit readers, too.
For myself, I've always used the reference documentation, and kind of
never really understood where some of the extra documentation of
certain features, like LIMIT/OFFSET, lived. I never realized there was
a narrative section. As a technically-minded geek, I go right to the
reference, and the other stuff is kind of a weird bonus that comes up
when I do a search.
So unless you're reading the documentation like a bound book, or had
glanced through each of the top-level pages of the TOC to familiarize
yourself with the structure, I'm not sure anyone would really
understand how the non-reference documentation was organized, or that
it wasn't meant to be authoritative.
> Still, the queries-limit.html page includes this statement: "OFFSET 0
> is the same as omitting the OFFSET clause." I don't see that there
> would be anything bad or confusing about changing it to read this way:
> "OFFSET 0 is the same as omitting the OFFSET clause, and LIMIT NULL is
> the same as omitting the LIMIT clause." In fact, it seems nicely
> symmetric.
My patch had done that, basically. The page mentions OFFSET ALL, and I
had just changed it to read OFFSET ALL or OFFSET NULL. Three little
words. :-)
Best,
David