diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 21f0d226ce..fdf000db2c 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -24,16 +24,15 @@
 
 /**
  * SECTION:gtkbox
- * @Short_description: A container box
+ * @Short_description: A container for packing widgets in a single row or column
  * @Title: GtkBox
- * @See_also: #GtkFrame, #GtkGrid, #GtkLayout
+ * @See_also: #GtkGrid
  *
- * The GtkBox widget organizes child widgets into a rectangular area.
- *
- * The rectangular area of a GtkBox is organized into either a single row
- * or a single column of child widgets depending upon the orientation.
- * Thus, all children of a GtkBox are allocated one dimension in common,
- * which is the height of a row, or the width of a column.
+ * The GtkBox widget arranges child widgets into a single row or column,
+ * depending upon the value of its #GtkOrientable:orientation property. Within
+ * the other dimension, all children are allocated the same size. Of course,
+ * the #GtkWidget:halign and #GtkWidget:valign properties can be used on
+ * the children to influence their allocation.
  *
  * GtkBox uses a notion of packing. Packing refers
  * to adding widgets with reference to a particular position in a
@@ -62,9 +61,6 @@
  * Use gtk_box_reorder_child() to move a GtkBox child to a different
  * place in the box.
  *
- * Note that a single-row or single-column #GtkGrid provides exactly
- * the same functionality as #GtkBox.
- *
  * # CSS nodes
  *
  * GtkBox uses a single CSS node with name box.
diff --git a/gtk/gtkgrid.c b/gtk/gtkgrid.c
index 553dc485e2..68c66adb52 100644
--- a/gtk/gtkgrid.c
+++ b/gtk/gtkgrid.c
@@ -39,10 +39,7 @@
  * @See_also: #GtkBox
  *
  * GtkGrid is a container which arranges its child widgets in
- * rows and columns. It is a very similar to #GtkBox,
- * but it consistently uses #GtkWidget’s #GtkWidget:margin and #GtkWidget:expand
- * properties instead of custom child properties, and it fully supports
- * [height-for-width geometry management][geometry-management].
+ * rows and columns, with arbitrary positions and horizontal/vertical spans.
  *
  * Children are added using gtk_grid_attach(). They can span multiple
  * rows or columns. It is also possible to add a child next to an
@@ -51,7 +48,8 @@
  *
  * GtkGrid can be used like a #GtkBox by just using gtk_container_add(),
  * which will place children next to each other in the direction determined
- * by the #GtkOrientable:orientation property.
+ * by the #GtkOrientable:orientation property. However, if all you want is a
+ * single row or column, then #GtkBox is the preferred widget.
  *
  * # CSS nodes
  *