diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md
index 19062904e2..08b89db518 100644
--- a/docs/getting-started/keeping-backstage-updated.md
+++ b/docs/getting-started/keeping-backstage-updated.md
@@ -9,6 +9,41 @@ latest releases. Backstage is more of a library than an application or service;
 similar to `create-react-app`, the `@backstage/create-app` tool gives you a
 starting point that's meant to be evolved.
 
+## Managing package versions with the Backstage yarn plugin
+
+The Backstage yarn plugin makes it easier to manage Backstage package versions,
+by determining the appropriate version for each package based on the overall
+Backstage version in backstage.json. This avoids the need to update every
+package.json across your Backstage monorepo, and means that when adding new
+`@backstage` dependencies, you don't need to worry about figuring out the right
+version to use to match the currently-installed release of Backstage.
+
+### Requirements
+
+In order to use the yarn plugin, you'll need to be using yarn 4.1.1 or greater.
+
+### Installation
+
+To install the yarn plugin, run the following command in your Backstage
+monorepo:
+
+```bash
+yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin
+```
+
+The resulting changes in the file system should be committed to your repo.
+
+### Usage
+
+When the yarn plugin is installed, versions for currently-released `@backstage`
+packages can be replaced in package.json with the string `"backstage:^"`. This
+instructs yarn to resolve the version based on the overall Backstage version in
+backstage.json.
+
+The `backstage-cli versions:bump` command documented below will detect the
+installation of the yarn plugin, and when it's installed, will automatically
+migrate dependencies across the monorepo to use it.
+
 ## Updating Backstage versions with backstage-cli
 
 The Backstage CLI has a command to bump all `@backstage` packages and
diff --git a/packages/yarn-plugin/README.md b/packages/yarn-plugin/README.md
index 16507713af..67ea19b1bd 100644
--- a/packages/yarn-plugin/README.md
+++ b/packages/yarn-plugin/README.md
@@ -9,5 +9,18 @@ version specified in the manifest for the Backstage release listed in
 backstage.json. If the dependent package is published, this version will be
 prefixed by `^`.
 
-**This plugin is still under active development, and requires some further
-testing before we recommend it for general use.**
+Detailed instructions for using the plugin can be found in [the docs](https://backstage.io/docs/getting-started/keeping-backstage-updated/#managing-package-versions-with-the-backstage-yarn-plugin).
+
+## Installation
+
+```bash
+yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin
+```
+
+The resulting changes in the file system should be committed to your repo.
+
+## Usage
+
+The yarn plugin recognizes the version string `"backstage:^"`, and replaces it
+with the appropriate version based on the overall Backstage version in
+backstage.json.