Re: Additional Chapter for Tutorial

On Wed, Sep 2, 2020 at 12:04 AM Jürgen Purtz <juergen(at)purtz(dot)de> wrote:

> On 01.09.20 23:30, Peter Eisentraut wrote:
> > It is mostly advanced low-level information that is irrelevant for
> > someone starting up,
>
> That applies only to the VACUUM chapter. VACUUM and AUTOVACUUM are
> controlled by a lot of parameters. Therefor the current documentation
> concerning the two mechanism spreads the description across different
> pages (20.4, 25.1, VACUUM command). Because of the structure of our
> documentation that's ok. But we should have a summary page somewhere -
> not necessarily in the tutorial.
>
> > the most part the information just duplicates what is already
> > explained elsewhere.
>
> That is the nature of a tutorial respectively a summary.
>
>
I've begun looking at this and have included quite a few html comments
within the patch. However, the two main items that I have found so far are:

One, I agree with Peter that this seems misplaced in Tutorial. I would
create a new Internals Chapter and place this material there, or maybe
consider a sub-chapter under "Overview of PostgreSQL Internals". If this
is deemed to be of a more primary importance than the content in the
Internals section I would recommend placing it in Reference. I feel it
does fit there and given the general importance of that section readers
will be inclined to click into it and skim over its content.

Two, I find the amount of detail being provided here to be on the too-much
side. A bit more judicious use of links into the appropriate detail
chapters seems warranted.

I took a pretty heavy hand to the original section though aside from the
scope comment it can probably be considered a bit weighted toward style
preferences. Though I did note/rewrite a couple of things that seemed
factually incorrect - and seemingly not done intentionally in the interest
of simplification. Specifically the client connection process and, I
think, the relationship between the checkpointer and background writer.

I do like the idea and the general flow of the material so far - though I
haven't really looked at the overall structure yet, just started reading
and editing from the top of the new file.

I've attached the original 0007 patch and my diff against it applied to
HEAD.

Took a quick peek at the image (at the end) and while I will need a second
pass over this section regardless I figured I'd provide this subset of
feedback now in order to move things along a bit.

David J.