diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index f1d29a52b9..cd113bb79b 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -408,6 +408,10 @@
         from ui files it run the command <command>gtk4-builder-tool simplify --replace</command>
         on them.
       </para>
+      <para>
+        The function gtk_widget_show_all(), the #GtkWidget::no-show-all property
+        and its getter and setter have been removed in  GTK+ 4, so you should stop using them.
+      </para>
     </section>
 
     <section>