diff --git a/docs/src/main/asciidoc/config-reference.adoc b/docs/src/main/asciidoc/config-reference.adoc
index c96912d08e7c5..598155e87df78 100644
--- a/docs/src/main/asciidoc/config-reference.adoc
+++ b/docs/src/main/asciidoc/config-reference.adoc
@@ -531,7 +531,10 @@ A secret configuration may be expressed as `${handler::value}`, where the `handl
 .application.properties
 [source,properties]
 ----
-my.secret=${aes-gcm-nopadding::DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg}
+= my.secret=${aes-gcm-nopadding::DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg}
+
+# the encryption key required to decode the secret. It can be set in any source.
+smallrye.config.secret-handler.aes-gcm-nopadding.encryption-key=somearbitrarycrazystringthatdoesnotmatter
 ----
 
 A lookup to `my.secret` will use the `SecretKeysHandler` name `aes-gcm-nopadding` to decode the value
@@ -540,6 +543,12 @@ A lookup to `my.secret` will use the `SecretKeysHandler` name `aes-gcm-nopadding
 For more information, please check SmallRye Config
 link:https://smallrye.io/smallrye-config/Main/config/secret-keys/[Secret Keys] documentation.
 
+[WARNING]
+====
+SmallRye Config may provide handlers not fully supported by Quarkus. Currently, only `smallrye-config-crypto` is
+supported.
+====
+
 == Accessing a generating UUID
 
 The default config source from Quarkus provides a random UUID value.