diff --git a/docs/docs/20-usage/20-workflow-syntax.md b/docs/docs/20-usage/20-workflow-syntax.md
index 58b523265..646312bb7 100644
--- a/docs/docs/20-usage/20-workflow-syntax.md
+++ b/docs/docs/20-usage/20-workflow-syntax.md
@@ -122,7 +122,13 @@ image: index.docker.io/library/golang
 image: index.docker.io/library/golang:1.7
 ```
 
-Woodpecker does not automatically upgrade container images. Example configuration to always pull the latest image when updates are available:
+Learn more how you can use images from [different registries](./41-registries.md).
+
+### `pull`
+
+By default, Woodpecker does not automatically upgrade container images and only pulls them when they are not already present.
+
+To always pull the latest image when updates are available, use the `pull` option:
 
 ```diff
  steps:
@@ -131,8 +137,6 @@ Woodpecker does not automatically upgrade container images. Example configuratio
 +    pull: true
 ```
 
-Learn more how you can use images from [different registries](./41-registries.md).
-
 ### `commands`
 
 Commands of every step are executed serially as if you would enter them into your local shell.
diff --git a/docs/versioned_docs/version-3.6/20-usage/20-workflow-syntax.md b/docs/versioned_docs/version-3.6/20-usage/20-workflow-syntax.md
index 58b523265..646312bb7 100644
--- a/docs/versioned_docs/version-3.6/20-usage/20-workflow-syntax.md
+++ b/docs/versioned_docs/version-3.6/20-usage/20-workflow-syntax.md
@@ -122,7 +122,13 @@ image: index.docker.io/library/golang
 image: index.docker.io/library/golang:1.7
 ```
 
-Woodpecker does not automatically upgrade container images. Example configuration to always pull the latest image when updates are available:
+Learn more how you can use images from [different registries](./41-registries.md).
+
+### `pull`
+
+By default, Woodpecker does not automatically upgrade container images and only pulls them when they are not already present.
+
+To always pull the latest image when updates are available, use the `pull` option:
 
 ```diff
  steps:
@@ -131,8 +137,6 @@ Woodpecker does not automatically upgrade container images. Example configuratio
 +    pull: true
 ```
 
-Learn more how you can use images from [different registries](./41-registries.md).
-
 ### `commands`
 
 Commands of every step are executed serially as if you would enter them into your local shell.