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