Re: Improve "3.6. Inheritance" tutorial

On Wed, Oct 7, 2026 at 6:00 PM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>
wrote:

> On Wed, 2026-10-07 at 16:28 -0300, Matemática A3K wrote:
> > 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:
> > >
> > >
> > > > 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.
> >
> > [...]
> >
> > 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.
>
> I personally am not convinced, but perhaps others agree with you.
>

No one is speaking up so far, let's see if we can come up with something
more clear or better.

Do you want to prepare a patch?

No problem, but let's keep iterating on this to see if we can arrive at an
even better solution.

>
> I think it would be best if we can avoid repeating the same information
> in several places. Such redundancy inflates the documentation and makes
> it harder to find all places that have to be fixed when something changes.
> Perhaps you can move things around to avoid that.
>

In this direction, if the "basic" tutorial is sourced from the "full"
tutorial, a comment on the
documentation should be put ("This is sourced as a basic tutorial, this
section should give
an overview of the feature and be self-contained.") and then, rewrite the
following to glue it.

The full tutorial should be:
- Overview
- Details
- Caveats

and the basic tutorial should be:
- Source from Overview
- Note: "If you find this feature useful for your case, continue reading
here where you will find
a more detailed discussion and the caveats to consider."

Something like this is what came to your mind?