Documentation/public-inbox-v1-format.pod | 4 ++++
 Documentation/public-inbox-v2-format.pod | 4 ++++
 script/public-inbox-compact              | 2 ++

diff --git a/Documentation/public-inbox-v1-format.pod b/Documentation/public-inbox-v1-format.pod
index 2a6b8d3c6f1c07b4073b827323c3a2a47022de90..3b0e70e1fc5f68039a114062af4b3b7282c4cc87 100644
--- a/Documentation/public-inbox-v1-format.pod
+++ b/Documentation/public-inbox-v1-format.pod
@@ -134,6 +134,10 @@ Since SCHEMA_VERSION 15 and the development of the v2 format,
 the "overview" DB also exists in the xapian directory for v1
 repositories.  See L<public-inbox-v2-format(5)/OVERVIEW DB>
 
+Our use of the L</OVERVIEW DB> requires Xapian document IDs to
+remain stable.  Thus, use of L<xapian-compact(1)> and
+L<copydatabase(8)> require the use of C<--no-renumber> switch.
+
 =item $GIT_DIR/ssoma.index
 
 This file is no longer used or created by public-inbox, but it is
diff --git a/Documentation/public-inbox-v2-format.pod b/Documentation/public-inbox-v2-format.pod
index 7dfe3296363b1c5032eca127ee13e901a364a9a8..bc58074e0de56fdfe0c791fea2ed44ad1a5eef2d 100644
--- a/Documentation/public-inbox-v2-format.pod
+++ b/Documentation/public-inbox-v2-format.pod
@@ -117,6 +117,10 @@ Rotational storage devices are NOT recommended for indexing of
 large mail archives; but are fine for backup and usable for
 small instances.
 
+Our use of the L</OVERVIEW DB> requires Xapian document IDs to
+remain stable.  Thus, use of L<xapian-compact(1)> and
+L<copydatabase(8)> require the use of C<--no-renumber> switch.
+
 =head2 OVERVIEW DB
 
 Towards the end of v2 development, it became apparent Xapian did
diff --git a/script/public-inbox-compact b/script/public-inbox-compact
index d22e40323dfef08b513aea2d8a4c95f0137dc5a1..395eec37a4cff439cc2d1db1afbac81e9fb2fa95 100755
--- a/script/public-inbox-compact
+++ b/script/public-inbox-compact
@@ -51,6 +51,8 @@ 	rename($new, $old) or die "rename $new => $old: $!\n";
 	$im->lock_release;
 	remove_tree("$old/old") or die "failed to remove $old/old: $!\n";
 }
+
+# we rely on --no-renumber to keep docids synched to NNTP
 my @compact = qw(xapian-compact --no-renumber);
 if ($v == 2) {
 	require PublicInbox::V2Writable;