On Wed, Jan 29, 2025 at 6:03 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Tue, Jan 28, 2025 at 7:59 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
> >
> > On Thu, Jan 23, 2025 at 9:58 AM vignesh C <vignesh21@gmail.com> wrote:
> > >
> >
> > I have pushed the remaining part of this patch. Now, we can review the
> > proposed documentation part.
> >
> > I feel we don't need the Examples sub-section for this part of the
> > docs. The behavior is quite clear from the "Behavior Summary"
> > sub-section table.
>
> It is good to hear that the "Behavior Summary" matrix is clear, but it
> is never the purpose of examples to show behaviour that is not already
> clearly documented. The examples are simply to demonstrate some real
> usage. Personally, I find it far easier to understand this (or any
> other) feature by working through a few examples in conjunction with
> the behaviour matrix, instead of just having the matrix and nothing
> else.
>
I am not against giving examples in the docs to make the topic easy to
understand but in this particular case, I am not sure if additional
examples are useful. You already gave one example in the beginning:
"For example, note below that subscriber table generated column value
comes from the subscriber column's calculation." the remaining text is
clear enough to understand the feature.
If you still want to make a case for additional examples, divide this
patch into two parts. The first part without examples could be part of
this thread and I can commit that. Then you can start a separate
thread just for the examples and then we can see what others think and
make a decision based on that.
--
With Regards,
Amit Kapila.
