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.albe@cybertec.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?
