Re: Additional Chapter for Tutorial

On 30.04.20 14:31, Jürgen Purtz wrote:
> On 29.04.20 21:12, Peter Eisentraut wrote:
>>
>> I don't see this really as belonging into the tutorial.  The tutorial
>> should be hands-on, how do you get started, how do you get some results.
>>
> Yes, the tutorial should be a short overview and give instructions how
> to start. IMO the first 4 sub-chapters fulfill this expectation.
> Indeed, the fifth (VACUUM) is extensive and offers many details.
>
> During the inspection of the existing documentation I recognized that
> there are many details about VACUUM, AUTOVACUUM, all of their
> parameters as well as their behavior. But the information is spread
> across many pages: Automatic Vacuuming, Client Connection Defaults,
> Routine Vacuuming, Resource Consumption, VACUUM. Even for a person
> with some pre-knowledge it is hard to get an overview how this fits
> together and why things are solved in exactly this way. In the end we
> have very good descriptions of all details but I miss the 'big
> picture'. Therefore I summarized central aspects and tried to give an
> answer to the question 'why is it done in this way?'. I do not dispute
> that the current version of the page is not adequate for beginners.
> But at some place we should have such a summary about vacuuming and
> freezing.
>
> How to proceed?
>
> - Remove the page and add a short paragraph to the MVCC page instead.
>
> - Cut down the page to a tiny portion.
>
> - Divide it into two parts: a) a short introduction and b) the rest
> after a statement like 'The following offers more details and
> parameters that are more interesting for an experienced user than for
> a beginner. You can easily skip it.'
>
>
>> Your material is more of an overview of the whole system.  What's a
>> new user supposed to do with that?
>
> When I dive into a new subject, I'm more interested in its
> architecture than in its details. We shall offer an overview about the
> major PG components and strategies to beginners.
>
>
In comparison with to previous patch this one contains:

- Position and title changed to reflect its intention and importance.

- A <note> delimits VACUUM basics from details. This is done because I
cannot find another suitable place for such a summarizing description.

- Three additional sub-chapters.

--

Jürgen Purtz