diff --git a/README.md b/README.md
index 8f874e8..37682a5 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,10 @@
 [![Test workflow](https://img.shields.io/github/workflow/status/docker/build-push-action/test?label=test&logo=github&style=flat-square)](https://github.com/docker/build-push-action/actions?workflow=test)
 [![Codecov](https://img.shields.io/codecov/c/github/docker/build-push-action?logo=codecov&style=flat-square)](https://codecov.io/gh/docker/build-push-action)
 
-## Upgrade
+## Upgrade from v1
 
-`v2` of this action changes drastically and now uses Docker [Buildx](https://github.com/docker/buildx). It works with
-3 new actions ([login](https://github.com/docker/login-action), [setup-buildx](https://github.com/docker/setup-buildx-action)
+`v2` of this action includes significant updates and now uses Docker [Buildx](https://github.com/docker/buildx). It
+works with 3 new optional actions ([login](https://github.com/docker/login-action), [setup-buildx](https://github.com/docker/setup-buildx-action)
 and [setup-qemu](https://github.com/docker/setup-qemu-action)) that we have created. It's also rewritten as a
 [typescript-action](https://github.com/actions/typescript-action/) to be as closed as possible of the
 [GitHub Runner](https://github.com/actions/virtual-environments) during its execution (#71 #92).
diff --git a/UPGRADE.md b/UPGRADE.md
index 54916a0..7f017d9 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -2,11 +2,12 @@
 
 ## v1 to v2
 
-* Rename `path` input to `context`
-* Rename `dockerfile` input to `file`
-* Rename `always_pull` input to `pull`
+* Input `path` is now called `context` for consistency with other Docker build tools
+* `path` defaults to current git repository so checkout action is not required in a workflow
+* Rename `dockerfile` input to `file` for consistency with other Docker build tools
+* Rename `always_pull` input to `pull` for consistency with other Docker build tools
 * Add `builder` input to be able to choose a builder instance through our [setup-buildx action](https://github.com/docker/setup-buildx-action)
-* Add [`platforms`](https://github.com/docker/buildx#---platformvaluevalue) input
+* Add [`platforms`](https://github.com/docker/buildx#---platformvaluevalue) input to support multi-platform builds
 * Add [`allow`](https://github.com/docker/buildx#--allowentitlement) input
 * Add [`load`](https://github.com/docker/buildx#--load) input
 * Add [`outputs`](https://github.com/docker/buildx#-o---outputpath-typetypekeyvalue) input