diff --git a/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
--- a/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
@@ -448,6 +448,13 @@
 
 It is possible to set `DEPRECATED` without an `EXPIRATION_DATE` (for instance, recommending a newer version of the port), but the converse does not make any sense.
 
+[NOTE]
+====
+When marking a port as `DEPRECATED`, if there are any alternative ports that can
+be used as a replacement for the one being deprecated, it is convenient to
+mention them in the commit message.
+====
+
 There is no set policy on how much notice to give.
 Current practice seems to be one month for security-related issues and two months for build issues.
 This also gives any interested committers a little time to fix the problems.