Re: Documentation improvements for partitioning

On 2017/02/15 12:00, Robert Haas wrote:
> On Fri, Feb 10, 2017 at 3:00 AM, Simon Riggs <simon(at)2ndquadrant(dot)com> wrote:
>
>> Without claiming I'm happy about this, I think the best way to improve
>> the number of eyeballs on this is to commit these docs as is.
>>
>> For me, the most important thing is understanding the feature, not
>> (yet) discussing what the docs should look like. This is especially
>> true if other patches reference the way partitioning works and nobody
>> can comment on those patches because they don't understand
>>
>> Any issues with that?
>
> There are a number of things that I think are awkward about the patch
> as committed:
>
> + <listitem>
> + <para>
> + See last section for some general information:
> + <xref linkend="ddl-partitioned-tables">
> + </para>
> + </listitem>
>
> I think we generally try to write the documentation in such a way as
> to minimize backward references, and a backward reference to the
> previous section seems particularly odd. We've now got section "5.10
> Partitioned Tables" followed immediately by section "5.11
> Partitioning", where the latter seems to think that you haven't read
> the former.
>
> I think that section 5.11 needs a much heavier rewrite than what it
> got as part of this patch. It's a hodgepodge of the old content
> (which explained how to fake partitioning when we didn't have an
> explicit concept of partitioning) and new content that talks about how
> the new way is different from the old way. But now that we have the
> new way, I'm guessing that most people are going to use that and not
> care about the old way any more. I'm not that it's even appropriate
> to keep the lengthy explanation of how to fake table partitioning
> using table inheritance and non-overlapping CHECK constraints, but if
> we still want that stuff it should be de-emphasized more than it is
> here. Probably the section should be retitled: in previous releases
> we called this "Partitioning" because we had no explicit notion of
> partitioning, but now that we do, it's confusing to have a section
> called "Partitioning" that explains how to avoid using the
> partitioning feature, which is more or less what this does. Or maybe
> the section title should stay the same (or this should be merged into
> the previous section?) but rewritten to change the emphasis.

I agree that my patch failed to de-emphasize the old partitioning method
enough. The examples in 5.11 Partitioning chapter also did not highlight
the new partitioning feature as much as it should have been, so it indeed
reads like a description of how to avoid using the new partitioning
feature. Should we completely remove details about the older partitioning
methods?

I like the idea of merging what are now two chapters into one and call it
Partitioned Tables, retaining the text that describes concepts while
getting rid of the texts detailing inheritance implementation. Perhaps
with the following sub-sections:

5.10 Partitioned Tables

5.10.1 When To Use Partitioning? (what is now 5.11.1 Overview)

5.10.2 Example (what is now 5.11.2. Implementing Partitioning)

5.10.3 Managing Partitions (same title as 5.11.3)

5.10.4. Partitioning and Constraint Exclusion (same title as 5.11.4)

About this, do we want to emphasize the fact that the new partitioned
tables *currently* depend on constraint exclusion? I guess not. So the
sub-section is retained most as is, with some tweaks.

5.10.5 Caveats (that still are)

As mentioned above, the above sub-sections will retain the old text that
talks about concepts and not the particular implementation details. For
example, in 5.10.3 Managing Partitions, the following text will be retained:

<sect2 id="ddl-partitioning-managing-partitions">
<title>Managing Partitions</title>

<para>
Normally the set of partitions established when initially
defining the table are not intended to remain static. It is
common to want to remove old partitions of data and periodically
add new partitions for new data. One of the most important
advantages of partitioning is precisely that it allows this
otherwise painful task to be executed nearly instantaneously by
manipulating the partition structure, rather than physically moving large
amounts of data around.
</para>

I will go make a patch for this if there are no objections. Suggestions
are welcome.

Thanks,
Amit