Re: Improve "3.6. Inheritance" tutorial

On Wed, Oct 7, 2026 at 11:43 AM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>
wrote:

> On Fri, 2026-10-02 at 12:23 -0300, Matemática A3K wrote:
> > On Fri, Oct 2, 2026 at 3:58 AM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>
> wrote:
> > > On Thu, 2026-10-01 at 18:55 +0000, PG Doc comments form wrote:
> > > > Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
> > > >
> > > > I propose the following modifications: [...]
> > >
> > > Do I get you right that you don't have any problems with the
> > > technical content, but are unhappy about the style?
> >
> > No, I'm unhappy with both, my suggestions go in both directions.
>
> I must say that I perfer the original style.
> But let's discuss the technical content:
>

OK

> > The main technical concern is that querying is not explained on it, it's
> > explained on the "details page".
> >
> > More in concrete, if you add "In PostgreSQL, a table can inherit from
> zero
> > or more other tables, and a query can reference either all rows of a
> table
> > or all rows of a table plus all of its descendant tables. The latter
> behavior
> > is the default." should be a "complete" explanation of the feature.
>
> I think the explanation in the tutorial is quite clear:
>
> Here the ONLY before cities indicates that the query should be run over
> only the cities table, and not tables below cities in the inheritance
> hierarchy. Many of the commands that we have already discussed — SELECT,
> UPDATE, and DELETE — support this ONLY notation.
>

Here, "quite clear" is the discrepancy.

After careful re-reading, the concepts are there, so it is "technically
correct" in that sense.

My point arose from the first iteration on it. If you follow the link at
the end of the page for more details, you end up reading an extended
tutorial, which I find to be "complete" on the subject.

Once you read the extended tutorial, the "summarized" tutorial (the page we
are discussing) becomes "clear" and "technically correct".

My impression is that this happens *after* you read the full version, adding
that sentence to the summary would make it more clear for some users.

> A tutorial is not supposed to provide a rigorous definition. Such a
> definition should be in the reference manual.

And indeed I find in
> https://www.postgresql.org/docs/18/sql-select.html
>
> If ONLY is specified before the table name, only that table is scanned.
> If ONLY is not specified, the table and all its descendant tables
> (if any) are scanned.
>
> I'm happy with the page the way it is...
>

OK, an "arguably" improvement is not worth submitting, can you confirm this
so this conversation becomes "finished" to me? Thanks!

> Yours,
> Laurenz Albe
>