diff --git a/docs/source/upgrade_notes.rst b/docs/source/upgrade_notes.rst
index c19b1938c..320f5baae 100644
--- a/docs/source/upgrade_notes.rst
+++ b/docs/source/upgrade_notes.rst
@@ -17,7 +17,11 @@ Upgrade Notes
     trigger:
       type: "core.st2.action.file_written"
 
-* Support for Mistral workflows was removed. Before upgrading to v3.3, ensure all Mistral workflows have been converted to Orquesta workflows. A tool is available for assisting in this conversion, more information can be found in the ``orquestaconvert`` `README.md <https://github.com/StackStorm/orquestaconvert/blob/master/README.md>`_.
+* Support for Mistral workflows was removed. Before upgrading to v3.3, ensure all Mistral workflows
+  have been converted to Orquesta workflows. Please review the :doc:`Orquesta </orquesta/index>` documentation for
+  details on how these differ from Mistral workflows, some re-design may be required.
+  A tool is available for assisting in this conversion, more information can be found
+  in the ``orquestaconvert`` `README.md <https://github.com/StackStorm/orquestaconvert/blob/master/README.md>`_.
 
 * The installation script now installs MongoDB 4.0 by default (previously, 3.4 was installed on
   RHEL/CentOS 7.x and Ubuntu 16.04).