Updated InkWell, InkResponse troubleshooting doc (#14473)
diff --git a/packages/flutter/lib/src/material/ink_well.dart b/packages/flutter/lib/src/material/ink_well.dart
index 588f53a..263d658 100644
--- a/packages/flutter/lib/src/material/ink_well.dart
+++ b/packages/flutter/lib/src/material/ink_well.dart
@@ -162,9 +162,19 @@
///
/// If there is an opaque graphic, e.g. painted using a [Container], [Image], or
/// [DecoratedBox], between the [Material] widget and the [InkResponse] widget,
-/// then the splash won't be visible because it will be under the opaque
-/// graphic. To avoid this problem, consider using an [Ink] widget to draw the
-/// opaque graphic itself on the [Material], under the ink splash.
+/// then the splash won't be visible because it will be under the opaque graphic.
+/// This is because ink splashes draw on the underlying [Material] itself, as
+/// if the ink was spreading inside the material.
+///
+/// The [Ink] widget can be used as a replacement for [Image], [Container], or
+/// [DecoratedBox] to ensure that the image or decoration also paints in the
+/// [Material] itself, below the ink.
+///
+/// If this is not possible for some reason, e.g. because you are using an
+/// opaque [CustomPaint] widget, alternatively consider using a second
+/// [Material] above the opaque widget but below the [InkResponse] (as an
+/// ancestor to the ink response). The [MaterialType.transparency] material
+/// kind can be used for this purpose.
///
/// See also:
///
@@ -556,9 +566,19 @@
///
/// If there is an opaque graphic, e.g. painted using a [Container], [Image], or
/// [DecoratedBox], between the [Material] widget and the [InkWell] widget, then
-/// the splash won't be visible because it will be under the opaque graphic. To
-/// avoid this problem, consider using an [Ink] widget to draw the opaque
-/// graphic itself on the [Material], under the ink splash.
+/// the splash won't be visible because it will be under the opaque graphic.
+/// This is because ink splashes draw on the underlying [Material] itself, as
+/// if the ink was spreading inside the material.
+///
+/// The [Ink] widget can be used as a replacement for [Image], [Container], or
+/// [DecoratedBox] to ensure that the image or decoration also paints in the
+/// [Material] itself, below the ink.
+///
+/// If this is not possible for some reason, e.g. because you are using an
+/// opaque [CustomPaint] widget, alternatively consider using a second
+/// [Material] above the opaque widget but below the [InkWell] (as an
+/// ancestor to the ink well). The [MaterialType.transparency] material
+/// kind can be used for this purpose.
///
/// See also:
///
