Re: Optimizing the documentation - Mailing list pgsql-hackers

From Joshua Drake
Subject Re: Optimizing the documentation
Date
Msg-id CAJvJg-Qev=DbkrJhruYxKysjGX+=0NKyfe+gbQOfrA36LH-AVg@mail.gmail.com
Whole thread Raw
In response to Re: Optimizing the documentation  (Tom Lane <tgl@sss.pgh.pa.us>)
Responses Re: Optimizing the documentation
List pgsql-hackers


In short, the devil's in the details.  Maybe there are lots of
places where this type of approach would help, but I think it's
going to be a case-by-case discussion not something where there's
a clear win overall.

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.

The reason I bolded and capitalized WHERE was to provide a visual signal to the example that is on the page. I could also argue that we could remove "For example," though I understand its purpose here.

Again, this was just a quick review.

JD
 

pgsql-hackers by date:

Previous
From: "David G. Johnston"
Date:
Subject: Re: Optimizing the documentation
Next
From: Peter Geoghegan
Date:
Subject: Re: Optimizing the documentation