diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index a682575a9bcf8..0a1becee85695 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -2678,14 +2678,10 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
 
 /// A box with a specified size.
 ///
-/// If given a child, this widget forces it to have a specific width and/or height.
-/// These values will be ignored if this widget's parent does not permit them.
-/// For example, this happens if the parent is the screen (forces the child to
-/// be the same size as the parent), or another [SizedBox] (forces its child to
-/// have a specific width and/or height). This can be remedied by wrapping the
-/// child [SizedBox] in a widget that does permit it to be any size up to the
-/// size of the parent, such as [Center] or [Align].
+/// {@youtube 560 315 https://www.youtube.com/watch?v=EHPu_DzRfqA}
 ///
+/// If given a child, this widget will try to size its child as close to the
+/// specified [height] and [width] as possible given the parent's constraints.
 /// If either the width or height is null, this widget will try to size itself to
 /// match the child's size in that dimension. If the child's size depends on the
 /// size of its parent, the height and width must be provided.
@@ -2698,8 +2694,6 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
 /// sizes itself to fit the parent. It is equivalent to setting [width] and
 /// [height] to [double.infinity].
 ///
-/// {@youtube 560 315 https://www.youtube.com/watch?v=EHPu_DzRfqA}
-///
 /// {@tool snippet}
 ///
 /// This snippet makes the child widget (a [Card] with some [Text]) have the
@@ -2714,6 +2708,36 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
 /// ```
 /// {@end-tool}
 ///
+/// ## Troubleshooting
+///
+/// ### Why is my [SizedBox] ignored?
+///
+/// In Flutter's layout protocol constraints go down, and sizes go up.
+/// A widget must respect the constraints passed by its parent. This can cause a
+/// [SizedBox]'s values to be ignored:
+///
+/// {@tool snippet}
+///
+/// This snippet makes the [ColoredBox] size 200x200. The 100x100 size is
+/// ignored because it is incompatible with its parent constraints of exactly
+/// 200x200:
+///
+/// ```dart
+/// const SizedBox(
+///   width: 200.0,
+///   height: 200.0,
+///   child: SizedBox( // Ignored!
+///     width: 100.0,
+///     height: 100.0,
+///     child: ColoredBox(color: Colors.green),
+///   ),
+/// )
+/// ```
+/// {@end-tool}
+///
+/// This can be fixed by wrapping the child [SizedBox] in a widget that lets
+/// it be any size up to the size of the parent, such as [Center] or [Align].
+///
 /// See also:
 ///
 ///  * [ConstrainedBox], a more generic version of this class that takes