docs: refine documentation

README.md

@@ -2,17 +2,19 @@
 
 _:warning: This app is under development and is not ready to be used._
 
-A GitHub app that mirrors releases of your bazel ruleset to the [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry).
+A GitHub app that mirrors releases of your Bazel ruleset to the [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry).
 
 ## Prerequisites
 
-See the [Bzlmod User Guide](https://bazel.build/docs/bzlmod) for how to make your ruleset ready for bzlmod.
+Prepare your ruleset for bzlmod by following the [Bzlmod User Guide](https://bazel.build/docs/bzlmod).
 
 ## How it works
 
-1. [Add the app](https://github.com/apps/publish-to-bcr) to your ruleset repository and to your fork of [bazelbuild/bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry). The fork can be in the same GitHub account as your ruleset or in your personal account.
-1. Include these [template files](templates/README.md) to your ruleset repository.
-1. Cut a release. You will be tagged in a pull request against the BCR with an entry for your module.
+1. [Configure](https://github.com/apps/publish-to-bcr) the app for:
+   - Your ruleset repository
+   - A fork of [bazelbuild/bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry). The fork can be in the same GitHub account as your ruleset _or_ in your personal account.
+1. Include these [template files](templates/README.md) in your ruleset repository.
+1. Cut a release. You will be tagged in a pull request against the BCR.
 
 ## Reporting issues
 

deployment/README.md

@@ -2,22 +2,21 @@
 
 This will walk you through deploying the Publish to BCR app.
 
-To deploy a new instance of the app, see [First time setup](#first-time-setup). To deploy to an already existing
-instance, see [Setup for existing deployment](#setup-for-existing-deployment).
+If the app has already been deployed, see [Setup for existing deployment](#setup-for-existing-deployment).
 
 ## First time setup
 
-Follow these steps to deploy an app environment for the first time.
-
 ### Create GitHub apps
 
-You must create two GitHub applications, the Webhook App which will respond to ruleset release
-events and publish an new entry to a fork, as well as a Bot App which posts pull requests to the
-Bazel Central Registry.
+Create two GitHub applications:
+
+1. Webhook app: responds to ruleset release events and publish an new entry to a Bazel Central Registry fork.
+2. Bot App: posts pull requests to the Bazel Central Registry.
 
-The purpose of the Bot App is to use a more restricted set of permissions when installed to
-the Bazel Central Registry compared to the more permissive permissions required on the Webhook
-App which is installed to ruleset repositories and BCR forks.
+Technically we could use one Github app, but we want to minimize the permissions granted to any
+app by the BCR. The Bot app's permissions are restricted to posting pull requests and is the one
+that gets installed to the BCR. The Webhook app is installed onto ruleset repos and BCR forks, and
+is responsible for pushing new entries to the fork.
 
 ### Create project
 
@@ -90,7 +89,7 @@ Under Event subscriptions, check:
 
 - Release
 
-### Bot App
+#### Bot App
 
 Under Repository permissions, set:
 

templates/.bcr/source.template.json

@@ -1,5 +1,5 @@
 {
-  "integrity": "**leave this alone**",
+  "integrity": "",
   "strip_prefix": "{REPO}-{VERSION}",
   "url": "https://github.com/{OWNER}/{REPO}/archive/refs/tags/{TAG}.tar.gz"
 }

templates/README.md

@@ -67,7 +67,7 @@ The `integrity` hash will automatically be filled out by the app.
 
 ```jsonc
 {
-  "integrity": "**leave this alone**", // <-- Don't touch this
+  "integrity": "", // <-- Leave this alone
   "strip_prefix": "{REPO}-{VERSION}",
   "url": "https://github.com/{OWNER}/{REPO}/archive/refs/tags/{TAG}.tar.gz"
 }