diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index f53e3c6bec..036ffafd57 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2833,8 +2833,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>
 
@@ -2965,6 +2966,17 @@ VALUES ('Albany', NULL, NULL, 'NY');
      offer flexibility but do not have some of the performance benefits
      of built-in declarative partitioning.
     </para>
+
+    <note>
+     <para>
+      Whether using table inheritance or declarative partitioning, 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.  When inheritance is used, see also the limitations
+      described in <xref linkend="ddl-partitioning-constraint-exclusion"/>.
+     </para>
+    </note>
    </sect2>
 
   <sect2 id="ddl-partitioning-declarative">