diff --git a/src/7-to-8/major-changes/config-changes.rst b/src/7-to-8/major-changes/config-changes.rst
index ad40417853..3efde4e5c8 100644
--- a/src/7-to-8/major-changes/config-changes.rst
+++ b/src/7-to-8/major-changes/config-changes.rst
@@ -9,6 +9,11 @@ The old configurations are now deprecated, but still supported.
 These will be highlighted upon ``cylc validate`` after renaming ``suite.rc``
 to ``flow.cylc``.
 
+Because some workflows use Jinja2 or EmPy branches which may not be switched on at
+the time of the initial ``cylc validate`` we have also provided
+a script, :ref:`cylc lint -r 728 <cylc_lint_script>` to check for Cylc 7
+syntax which may be deprecated.
+
 There are some examples below of how to upgrade:
 
 .. _7-to-8.graph_syntax:
diff --git a/src/user-guide/writing-workflows/configuration.rst b/src/user-guide/writing-workflows/configuration.rst
index 01e79eb457..5869dc76c7 100644
--- a/src/user-guide/writing-workflows/configuration.rst
+++ b/src/user-guide/writing-workflows/configuration.rst
@@ -141,3 +141,11 @@ All legal entries are documented in the :cylc:conf:`flow.cylc` reference.
 
 If a :cylc:conf:`flow.cylc` file uses include-files ``cylc view`` will
 show an inlined copy of the workflow with correct line numbers.
+
+.. _cylc_lint_script:
+
+``cylc lint``
+^^^^^^^^^^^^^
+
+.. automodule:: cylc.flow.scripts.lint
+
diff --git a/src/workflow-design-guide/style-guide.rst b/src/workflow-design-guide/style-guide.rst
index 0235daf060..fa8b4e61f2 100644
--- a/src/workflow-design-guide/style-guide.rst
+++ b/src/workflow-design-guide/style-guide.rst
@@ -5,6 +5,10 @@ Coding style is largely subjective, but for collaborative development of
 complex systems it is important to settle on a clear and consistent style to
 avoid getting into a mess. The following style rules are recommended.
 
+.. seealso::
+
+   :ref:`cylc lint -r style <cylc_lint_script>` is a tool designed to help
+   you check your code style.
 
 Tab Characters
 --------------