Re: Additional Chapter for Tutorial

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.

--

Jürgen Purtz