diff --git a/doc/ref/states/highstate.rst b/doc/ref/states/highstate.rst
index 5d2b278cde..01b09968d9 100644
--- a/doc/ref/states/highstate.rst
+++ b/doc/ref/states/highstate.rst
@@ -59,6 +59,9 @@ ID declaration
 
         Occurs on the top level or under the :term:`extend declaration`.
 
+        Must **not** contain a dot, otherwise highstate summary output will be
+        unpredictable.
+
 Extend declaration
 ------------------
 
diff --git a/doc/topics/tutorials/states_pt1.rst b/doc/topics/tutorials/states_pt1.rst
index 244dfc2505..62dc486540 100644
--- a/doc/topics/tutorials/states_pt1.rst
+++ b/doc/topics/tutorials/states_pt1.rst
@@ -81,6 +81,9 @@ In this case it defines the name of the package to be installed. **NOTE:** the
 package name for the Apache httpd web server may differ on your OS or distro —
 for example, on Fedora it is ``httpd`` but on Debian/Ubuntu it is ``apache2``.
 
+Additionally, an ID declaration should not contain a dot, as this will produce
+unpredictable output in the summary returned from a highstate.
+
 The second line, called the :term:`state declaration`, defines which of the
 Salt States we are using. In this example, we are using the :mod:`pkg state
 <salt.states.pkg>` to ensure that a given package is installed.