diff --git a/docs/reference/builder.md b/docs/reference/builder.md
index 8090aa94de..9180e6b78e 100644
--- a/docs/reference/builder.md
+++ b/docs/reference/builder.md
@@ -1292,8 +1292,9 @@ subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is
 defined and the `what_user` value was passed on the command line. Prior to its definition by an
 `ARG` instruction, any use of a variable results in an empty string.
 
-> **Note:** It is not recommended to use build-time variables for
->  passing secrets like github keys, user credentials etc.
+> **Warning:** It is not recommended to use build-time variables for
+>  passing secrets like github keys, user credentials etc. Build-time variable
+>  values are visible to any user of the image with the `docker history` command.
 
 You can use an `ARG` or an `ENV` instruction to specify variables that are
 available to the `RUN` instruction. Environment variables defined using the
diff --git a/man/Dockerfile.5.md b/man/Dockerfile.5.md
index 7d56bda0fa..df69935397 100644
--- a/man/Dockerfile.5.md
+++ b/man/Dockerfile.5.md
@@ -376,8 +376,9 @@ A Dockerfile is similar to a Makefile.
   defined and the `what_user` value was passed on the command line. Prior to its definition by an
   `ARG` instruction, any use of a variable results in an empty string.
 
-  > **Note:** It is not recommended to use build-time variables for
-  >  passing secrets like github keys, user credentials etc.
+  > **Warning:** It is not recommended to use build-time variables for
+  >  passing secrets like github keys, user credentials etc. Build-time variable
+  >  values are visible to any user of the image with the `docker history` command.
 
   You can use an `ARG` or an `ENV` instruction to specify variables that are
   available to the `RUN` instruction. Environment variables defined using the