diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
index 109e50a378..2f967ce0ca 100644
--- a/docs/source/changelog.rst
+++ b/docs/source/changelog.rst
@@ -44,6 +44,9 @@ Unreleased
 
 * java.security.cert.X509CRL serialization support added.
 
+* Shell (embedded available only in dev mode or via SSH) connects to the node via RPC instead of using the ``CordaRPCOps`` object directly.
+  To enable RPC connectivity ensure node’s ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present.
+
 .. _changelog_v3:
 
 Version 3.0
diff --git a/docs/source/upgrade-notes.rst b/docs/source/upgrade-notes.rst
index be5b870a5d..28d303566a 100644
--- a/docs/source/upgrade-notes.rst
+++ b/docs/source/upgrade-notes.rst
@@ -54,6 +54,8 @@ UNRELEASED
                         JoinColumn(name = "transaction_id", referencedColumnName = "transaction_id")))
                 override var participants: MutableSet<AbstractParty>? = null,
 
+* Shell - to use Shell ensure ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present.
+
 Testing
 ~~~~~~~