diff --git a/src/plots/cartesian/layout_attributes.js b/src/plots/cartesian/layout_attributes.js
index 3d81797b7e9..404f023eb71 100644
--- a/src/plots/cartesian/layout_attributes.js
+++ b/src/plots/cartesian/layout_attributes.js
@@ -687,8 +687,11 @@ module.exports = {
         editType: 'plot',
         description: [
             'If set a same-letter axis id, this axis is overlaid on top of',
-            'the corresponding same-letter axis.',
-            'If *false*, this axis does not overlay any same-letter axes.'
+            'the corresponding same-letter axis, with traces and axes visible for both',
+            'axes.',
+            'If *false*, this axis does not overlay any same-letter axes.',
+            'In this case, for axes with overlapping domains only the highest-numbered',
+            'axis will be visible.'
         ].join(' ')
     },
     layer: {