diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index a0a7435a03..a86cdd8ad0 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3450,8 +3450,9 @@ VALUES ('Albany', NULL, NULL, 'NY');
     </listitem>
    </itemizedlist>
 
-   These deficiencies will probably be fixed in some future release,
-   but in the meantime considerable care is needed in deciding whether
+   Some functionality not implemented for inheritance hierarchies is
+   implemented for declarative partitioning.
+   Considerable care is needed in deciding whether partitioning with legacy
    inheritance is useful for your application.
   </para>
 
@@ -3582,6 +3583,28 @@ VALUES ('Albany', NULL, NULL, 'NY');
      offer flexibility but do not have some of the performance benefits
      of built-in declarative partitioning.
     </para>
+
+    <note>
+     <para>
+      When using table inheritance, hierarchies with more than a few hundred
+      partitions are not recommended.  Such hierarchies may incur long
+      planning time, and, in the case of <command>UPDATE</command> and
+      <command>DELETE</command>, excessive memory usage.  See also the
+      limitations described in
+      <xref linkend="ddl-partitioning-constraint-exclusion"/>.
+     </para>
+
+     <para>
+      With declarative partitioning, larger partition hierarchies are more
+      manageable, up to perhaps several thousand partitions.  However, the
+      planning time and memory usage, especially with
+      <command>UPDATE</command> and <command>DELETE</command> is directly
+      related to the number of partitions that remain after the planner has
+      performed partition pruning.  Query plans containing large numbers of
+      partitions can also suffer from slower query execution times due to the
+      additional overheads in locking and the initialization of the plan.
+     </para>
+    </note>
    </sect2>
 
   <sect2 id="ddl-partitioning-declarative">