diff --git a/doc/source/main_features.rst b/doc/source/main_features.rst
index 9e6758e51..3c76634a5 100644
--- a/doc/source/main_features.rst
+++ b/doc/source/main_features.rst
@@ -138,6 +138,14 @@ There are different types of policies in Mistral.
 
 All parameter values for any policy can be defined as YAQL expressions.
 
+**NOTE:** It would be rare to use both break-on and continue-on in the same
+retry block. *break-on* should be used when one expects the action to be in an
+ERROR state for some amount of tries, but may eventually go to a SUCCESS state,
+thereby stopping the loop. But if *break-on* is *'true'* then the retries will
+stop and the task will be in ERROR. *continue-on* should be used if the action
+will usually return *SUCCESS*, but the action has other results that can be
+used to signal whether to continue the loop or not.
+
 Join
 ----
 
diff --git a/doc/source/user/wf_lang_v2.rst b/doc/source/user/wf_lang_v2.rst
index f0579ead8..28ad2e359 100644
--- a/doc/source/user/wf_lang_v2.rst
+++ b/doc/source/user/wf_lang_v2.rst
@@ -385,6 +385,14 @@ Retry policy can also be configured on a single line as:
 
 All parameter values for any policy can be defined as YAQL/Jinja2 expressions.
 
+**NOTE:** It would be rare to use both break-on and continue-on in the same
+retry block. *break-on* should be used when one expects the action to be in an
+ERROR state for some amount of tries, but may eventually go to a SUCCESS state,
+thereby stopping the loop. But if *break-on* is *'true'* then the retries will
+stop and the task will be in ERROR. *continue-on* should be used if the action
+will usually return *SUCCESS*, but the action has other results that can be
+used to signal whether to continue the loop or not.
+
 Input syntax
 ''''''''''''