diff --git a/doc/templates.rst b/doc/templates.rst
index 279c1b832..23fbb6a58 100644
--- a/doc/templates.rst
+++ b/doc/templates.rst
@@ -794,6 +794,21 @@ operand is contained in the right:
     You can use this operator to perform a containment test on strings,
     sequences, mappings, or objects implementing the ``Traversable`` interface.
 
+.. note::
+
+    For sequences, mappings, and ``Traversable`` objects, ``in`` uses a loose
+    comparison (similar to ``==``); use :doc:`same as <tests/sameas>` for a
+    strict comparison. Like PHP's ``in_array()``, this can yield unexpected
+    results when the left operand is a boolean:
+
+    .. code-block:: twig
+
+        {# returns true because true == 'foo' under PHP loose comparison #}
+        {{ true in ['foo', 'bar'] }}
+
+    Containment on strings only accepts string, integer, and float operands on
+    the left; other types always return ``false``.
+
 To perform a negative test, use the ``not in`` operator:
 
 .. code-block:: twig