diff --git a/content/build/building/secrets.md b/content/build/building/secrets.md
index b05f5986a4..479dfd63a0 100644
--- a/content/build/building/secrets.md
+++ b/content/build/building/secrets.md
@@ -61,17 +61,20 @@ The source of a secret can be either a
 When you use the CLI or Bake, the type can be detected automatically. You can
 also specify it explicitly with `type=file` or `type=env`.
 
-The following example mounts the environment variable `KUBECONFIG` to secret ID
-`kube`.
+The following example mounts the environment variable `KUBECONFIG` to secret ID `kube`,
+as a file in the build container at `/run/secrets/kube`.
 
 ```console
 $ docker build --secret id=kube,env=KUBECONFIG .
 ```
 
-The following example maps an environment variable directly to a secret ID.
+When you secrets from environment variables, you can omit the `id` parameter
+to bind the secret to a file with the same name as the variable.
+In the following example, the value of the `API_TOKEN` variable
+is mounted to `/run/secrets/API_TOKEN` in the build container.
 
 ```console
-$ docker build --secret env=KUBECONFIG .
+$ docker build --secret id=API_TOKEN .
 ```
 
 ### Target