diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index dfe76c0b2f..2e00bae4bf 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -79,7 +79,6 @@
       <xi:include href="xml/gtkactionbar.xml" />
       <xi:include href="xml/gtkheaderbar.xml" />
       <xi:include href="xml/gtkoverlay.xml" />
-      <xi:include href="xml/gtkalignment.xml" />
       <xi:include href="xml/gtkbbox.xml" />
       <xi:include href="xml/gtkpaned.xml" />
       <xi:include href="xml/gtklayout.xml" />
@@ -340,6 +339,7 @@
       <xi:include href="xml/gtkarrow.xml" />
       <xi:include href="xml/gtkstatusicon.xml" />
       <xi:include href="xml/gtkthemingengine.xml" />
+      <xi:include href="xml/gtkalignment.xml" />
     </chapter>
 
   </part>
diff --git a/gtk/deprecated/gtkalignment.c b/gtk/deprecated/gtkalignment.c
index 0b32553e64..54079f558f 100644
--- a/gtk/deprecated/gtkalignment.c
+++ b/gtk/deprecated/gtkalignment.c
@@ -40,9 +40,10 @@
  * Of course, if the scale settings are both set to 1, the alignment settings
  * have no effect.
  *
- * Note that the desired effect can in most cases be achieved by using the
- * #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties
- * on the child widget, so #GtkAlignment should not be used in new code.
+ * GtkAlignment has been deprecated in 3.14 and should not be used in
+ * newly-written code. The desired effect can be achieved by using the
+ * #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the
+ * child widget.
  */
 
 #include "config.h"
@@ -143,7 +144,7 @@ gtk_alignment_class_init (GtkAlignmentClass *class)
                                                       0.0,
                                                       1.0,
                                                       0.5,
-                                                      GTK_PARAM_READWRITE));
+                                                      GTK_PARAM_READWRITE|G_PARAM_DEPRECATED));
    
   g_object_class_install_property (gobject_class,
                                    PROP_YALIGN,
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 05c1bc07ae..0394a998d3 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1498,10 +1498,9 @@ _gtk_container_set_border_width_set (GtkContainer *container,
  * around the outside of the container. The only exception to this is
  * #GtkWindow; because toplevel windows can’t leave space outside,
  * they leave the space inside. The border is added on all sides of
- * the container. To add space to only one side, one approach is to
- * create a #GtkAlignment widget, call gtk_widget_set_size_request()
- * to give it a size, and place it on the side of the container as
- * a spacer.
+ * the container. To add space to only one side, use a specific
+ * #GtkWidget:margin property on the child widget, for example
+ * #GtkWidget:margin-top.
  **/
 void
 gtk_container_set_border_width (GtkContainer *container,