diff --git a/DOCS.md b/DOCS.md
index 7efe82e..0d70929 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -8,7 +8,7 @@ Registry: https://hub.docker.com/r/target/secret-vault
 
 ## Usage
 
-Sample of writing a secret using token authentication:
+Sample of retrieving a secret using token authentication:
 
 ```yaml
 secrets:
@@ -25,7 +25,7 @@ secrets:
             path: docker
 ```
 
-Sample of reading a secret using ldap authentication:
+Sample of retrieving a secret using ldap authentication:
 
 ```diff
 secrets:
@@ -64,6 +64,30 @@ secrets:
             path: docker
 ```
 
+Sample of retrieving a secret and writing it to multiple paths with a new key:
+```yaml
+secrets:
+  - origin:
+      name: vault
+      image: target/vela/secret-vault:latest
+      secrets:
+        - source: superSecretToken
+          target: vault_token
+      parameters:
+        addr: vault.company.com
+        auth_method: token
+        items:
+          # assume user_A has two keys: `id` and `token`, but we want it to be `username` and `password`
+          #
+          # this will write to `/vela/secrets/kaniko/username` and `/vela/secrets/kaniko/password`
+          # and also `/vela/secrets/artifactory/username` and `/vela/secrets/artifactory/password`
+          - source: secret/vela/user_A
+            path: [ kaniko, artifactory ]
+            keys:
+              id: username
+              token: password
+```
+
 ## Secrets
 
 **NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.**
@@ -104,14 +128,16 @@ The following parameters are used to configure the image:
 | `password`    | password for server authentication with ldap             | `false`   | `N/A`   |
 | `token`       | token for server authentication                          | `false`   | `N/A`   |
 | `username`    | set the log level for the plugin                         | `false`   | `N/A`   |
+| `items`       | set of secrets to retrieve and write to workspace        | `true`    | `N/A`   |
 
-#### Read
+### Items
 
-The following parameters are used to configure reading:
+| Name          | Description                                              | Required  | Default      |
+| ------------- | -------------------------------------------------------- | --------- | ------------ |
+| `source`      | path to secret                                           | `true`    | `N/A`        |
+| `path`        | desired file path under `vela/secrets/` directory        | `true`    | `N/A`        |
+| `keys`        | override Vault keys (map type)                           | `false`   | `vault key`  |
 
-| Name    | Description                                      | Required | Default |
-| ------- | ------------------------------------------------ | -------- | ------- |
-| `items` | enables pretending to perform the apply          | `true`  | `false` |
 
 ## Template