Re: Optimizing the documentation

Joshua Drake <jd(at)commandprompt(dot)com> writes:
> Certainly and I didn't want to just start dumping patches. Part of this is
> just style, for example:

> Thus far, our queries have only accessed one table at a time. Queries can
> access multiple tables at once, or access the same table in such a way that
> multiple rows of the table are being processed at the same time. A query
> that accesses multiple rows of the same or different tables at one time is
> called a join query. As an example, say you wish to list all the weather
> records together with the location of the associated city. To do that, we
> need to compare the city column of each row of the weather table with the
> name column of all rows in the cities table, and select the pairs of rows
> where these values match.

> It isn't "terrible" but can definitely be optimized. In a quick review, I
> would put it something like this:

> Queries can also access multiple tables at once, or access the same table
> in a way that multiple rows are processed. A query that accesses multiple
> rows of the same or different tables at one time is a join. For example, if
> you wish to list all of the weather records with the location of the
> associated city, we would compare the city column of each row of the weather
> table with the name column of all rows in the cities table, and select the
> rows *WHERE* the values match.

TBH, I'm not sure that that is an improvement at all. I'm constantly
reminded that for many of our users, English is not their first language.
A little bit of redundancy in wording is often helpful for them.

The places where I think the docs need help tend to be places where
assorted people have added information over time, such that there's
not a consistent style throughout a section; or maybe the information
could be presented in a better order. We don't need to be taking a
hacksaw to text that's perfectly clear as it stands.

(If I were thinking of rewriting this text, I'd probably think of
removing the references to self-joins and covering that topic
in a separate para. But that's because self-joins aren't basic
usage, not because I think the text is unreadable.)

> The reason I bolded and capitalized WHERE was to provide a visual signal to
> the example that is on the page.

IMO, typographical tricks are not something to lean on heavily.

regards, tom lane