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.
