diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst
index 8bc80b69e21..1b9acf30e8e 100644
--- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst
+++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst
@@ -75,6 +75,22 @@ Included file:
 
 The relevant change in those examples is, that in Ansible 2.5, the included file defines the tag ``distro_include`` again. The tag is not inherited automatically.
 
+Fixed handling of keywords and inline variables
+-----------------------------------------------
+
+We made several fixes to how we handle keywords and 'inline variables', to avoid conflating the two. Unfortunately these changes mean you must specify whether `name` is a keyword or a variable when calling roles. If you have playbooks that look like this::
+
+    roles:
+        - { role: myrole, name: Justin, othervar: othervalue, become: True}
+
+You will run into errors because Ansible reads name in this context as a keyword. Beginning in 2.5, if you want to use a variable name that is also a keyword, you must explicitly declare it as a variable for the role::
+
+    roles:
+        - { role: myrole, vars: {name: Justin, othervar: othervalue}, become: True}
+
+
+For a full list of keywords see ::ref::`Playbook Keywords`.
+
 
 Deprecated
 ==========