diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 5f971e3322e..51530ab8453 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -501,6 +501,15 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
         z = person.friends         # does not call
         x is z                     # is True
 
+    .. warning::
+
+        ``cached_property`` doesn't work properly with a mangled__ name unless
+        it's passed a ``name`` of the form ``_Class__attribute``::
+
+            __friends = cached_property(get_friends, name='_Person__friends')
+
+        __ https://docs.python.org/3/faq/programming.html#i-try-to-use-spam-and-i-get-an-error-about-someclassname-spam
+
 .. function:: keep_lazy(func, *resultclasses)
 
     Django offers many utility functions (particularly in ``django.utils``)