Merge branch 'doc-editing'

I spent some time last month editing all of the documentation, as an
excuse to try out Vale (for English prose linting).

Neither of the rule sets I tried satisfied me, and on a second pass I
found that I "fixed" some findings by introducing other, more obvious
errors. I'm glad I know about Vale now, but I don't plan on trying too
hard to integrate it into my workflow.

Either way, I think this is a good changeset.

Author: ahamlinman

README.md

@@ -23,10 +23,9 @@ You'll need the [Go][go] toolchain installed to try the demo program.
 1. Build the demo: `go build ./cmd/randomizer-demo`
 1. See what to do next: `./randomizer-demo help`
 
-The demo outputs the same text that would be sent to Slack, using proper
-[message formatting][format]. Groups are saved in a [bbolt][bbolt] database
-file in the current directory. This gives a rough taste of how the command
-works, and is helpful for testing.
+The demo saves groups in a [bbolt][bbolt] database in the current directory,
+and outputs responses using [Slack's "mrkdwn" format][format]. This gives a
+taste of how the command works, and helps with testing.
 
 [go]: https://golang.org/
 [format]: https://api.slack.com/docs/message-formatting
@@ -37,11 +36,10 @@ works, and is helpful for testing.
 This repo provides two guides on deploying the randomizer API for use with
 Slack:
 
-- `SERVERLESS.md` is a fairly detailed walkthrough for deployment on [AWS
+- `SERVERLESS.md` is a detailed walkthrough for deployment on [AWS
   Lambda][lambda], Amazon's managed function as a service platform.
-- `SERVERMORE.md` is a fairly high-level guide for setting up the
-  `randomizer-server` HTTP server, that assumes more background knowledge
-  and/or willingness to dive into details of both standard server management
-  and the randomizer implementation.
+- `SERVERMORE.md` is a high-level guide for configuring the `randomizer-server`
+  HTTP server. It assumes more background knowledge and/or willingness to dive
+  into the details of server management and the randomizer implementation.
 
 [lambda]: https://aws.amazon.com/lambda/

SERVERLESS.md

@@ -31,9 +31,9 @@ IAM][iam].
 
 ## Create an S3 Bucket
 
-When AWS Lambda starts up your function, it will download the compiled
-randomizer code from an [Amazon S3][s3] bucket. You can create a new S3 bucket
-using the AWS CLI:
+When AWS Lambda starts up your function, it downloads the compiled randomizer
+code from an [Amazon S3][s3] bucket. You can create a new S3 bucket using the
+AWS CLI:
 
 ```sh
 aws s3 mb s3://[name]
@@ -50,8 +50,8 @@ want a name that references yourself, your company, etc.
 
 The randomizer validates that each HTTP request legitimately came from Slack by
 checking for a special Slack-provided token value in the request parameters.
-Since this token is a secret value, we'll store it in the [AWS Systems Manager
-Parameter Store][ssm parameter store] with encryption.
+Since this token is a secret value, you should store it in the [AWS Systems
+Manager Parameter Store][ssm parameter store] with encryption.
 
 Note that the current version of the randomizer only supports the deprecated
 "Verification Token" to validate requests, and not the newer "Signing Secret"
@@ -66,19 +66,19 @@ aws ssm put-parameter --type SecureString --name /Randomizer/SlackToken --value
 ```
 
 The parameter name in the `aws ssm` command is unique within your AWS account,
-must start with a `/`, and can contain additional slash-separated parts to help
-you organize all of the SSM parameters in your account. While the parameter can
-be encrypted with the default AWS-managed SSM key, the CloudFormation template
-does not currently support encryption with a custom KMS key (which would cost
-$1/mo and require additional IAM and KMS setup).
+must start with a `/`, and can contain extra slash-separated parts to help
+organize all the SSM parameters in your account. While you can encrypt the
+parameter with the default AWS-managed SSM key, the CloudFormation template
+doesn't support encryption with a custom KMS key (which costs $1/mo and
+requires extra IAM and KMS setup).
 
 [ssm parameter store]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html
 
 ## Run the Initial Deployment
 
-Now, we're ready to use AWS [CloudFormation][CloudFormation] to deploy the
-randomizer into our account, with all necessary resources (e.g. the DynamoDB
-table for storing groups) automatically created and configured.
+Now, you'll use AWS [CloudFormation][CloudFormation] to deploy the randomizer
+into your account, with all necessary resources (like the DynamoDB table for
+storing groups) automatically created and configured.
 
 Similar to how you picked S3 bucket and SSM parameter names, you'll also need
 to pick a name for your CloudFormation "stack." Like your repository name, this
@@ -107,10 +107,10 @@ deployment:
 ./hfc build-deploy Randomizer  # or whatever other stack name you chose
 ```
 
-This command will automatically compile the randomizer code for AWS Lambda,
-upload it to your S3 bucket, and set it up for use. After some time, the script
-will finish and print the webhook URL for Slack. Copy and paste this into the
-"URL" field of your Slack slash command configuration, and save it.
+This command automatically compiles the randomizer code for AWS Lambda, uploads
+it to your S3 bucket, sets it up for use, and prints a webhook URL for Slack.
+Copy and paste this into the "URL" field of your Slack slash command
+configuration, and save it.
 
 At this point, you should be able to use the randomizer in your Slack
 workspace. Go ahead and try it out!
@@ -119,27 +119,27 @@ workspace. Go ahead and try it out!
 
 ## Upgrades and Maintenance
 
-To upgrade the randomizer deployment in your AWS account, run the above command
-in a newer version of the randomizer repository.
+To upgrade the randomizer deployment in your AWS account, run
+`./hfc build-deploy Randomizer` in a newer version of the repository.
 
 Run `./hfc help` to learn more about additional commands that might be useful.
 
 ## Notes
 
 - The CloudFormation template (Template.yaml) uses the [AWS SAM][sam]
   transformation to simplify the setup of the Lambda function.
-- The DynamoDB table in the template is provisioned in On-Demand capacity mode.
-  Note that this mode is not eligible for the AWS Free Tier. See the
-  documentation for [Read/Write Capacity Mode][capacity mode] for more details.
+- The template provisions the DynamoDB table in On-Demand capacity mode, which
+  isn't eligible for the AWS Free Tier. See the [Read/Write Capacity
+  Mode][capacity mode] documentation for details.
 - The default configuration enables [AWS X-Ray][x-ray] tracing for the function
   and its requests to DynamoDB. X-Ray is free for up to 100,000 traces per month
   for every AWS account, and it's useful to see where each request is spending
   time. However, you can turn it off by passing `XRayTracingEnabled=false` to
   the deployment script.
 - My co-workers and I collectively make a little over 500 requests to the
   randomizer per month, and at that small of a volume it's essentially free to
-  run on AWS even without the 12 month free tier. My _very rough_ estimate is
-  that the randomizer probably costs less than $1 per million requests.
+  run on AWS even without the 12 month free tier. My _rough_ estimate is that
+  the randomizer costs less than $1 per million requests.
 
 [sam]: https://github.com/awslabs/serverless-application-model
 [capacity mode]: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html

SERVERMORE.md

@@ -3,35 +3,35 @@
 `randomizer-server` is an HTTP server providing the Slack slash command API for
 the randomizer. This section provides general pointers on setting it up.
 
-This guide does **not** cover:
+This guide **doesn't** cover:
 
 - Proper server configuration and service management, whether directly on a
   server (systemd, Docker, Podman, etc.) or through an orchestrator
   (Kubernetes, HashiCorp Nomad, Docker Swarm, etc.).
 - Setting up a reverse proxy to provide SSL termination for the randomizer API
-  (as `randomizer-server` does not serve TLS out of the box).
+  (as `randomizer-server` doesn't serve TLS out of the box).
 - The specifics of configuring cloud credentials and access policies, should
-  you wish to use a cloud backend for group storage or secrets.
+  you wish to use a cloud provider for group storage or secrets.
 
-If you're uncomfortable with these topics or the level of detail provided
-below, and you aren't interested in self-study or trial and error to work
-through it all, the AWS Lambda setup might be preferable (see `SERVERLESS.md`).
+If you're uncomfortable with these topics or the rest of this guide, and you
+aren't interested in learning them, you might prefer the AWS Lambda setup in
+`SERVERLESS.md`.
 
-In addition to the environment variables below, check `randomizer-server -help`
-for CLI flags that you may wish to set, e.g. the bind address for the server
+In addition to the environment variables below, see `randomizer-server -help`
+for CLI flags that you may wish to set, like the bind address for the server
 (defaults to ":7636").
 
 ## Slack Token
 
 Regardless of the group storage backend, you'll need to configure one of the
 following environment variables to set the Slack slash command verification
-token (sorry, the newer signing secret configuration is not yet supported):
+token (the newer signing secret configuration isn't supported):
 
 - `SLACK_TOKEN`: Set to the value of the token itself.
 - `SLACK_TOKEN_SSM_PATH`: The path to an AWS SSM Parameter Store parameter
   containing the value of the verification token. This requires appropriate AWS
   configuration in the environment. You can also set `SLACK_TOKEN_SSM_TTL` to a
-  Go duration to control how long the SSM lookup is cached for (default 2m).
+  Go duration to control how long the SSM lookup remains cached (default 2m).
 
 ## Storage Backends
 
@@ -40,14 +40,13 @@ token (sorry, the newer signing secret configuration is not yet supported):
 [bbolt][bbolt] is the local key-value database engine behind systems like etcd,
 Consul, InfluxDB 2.x, and more.
 
-The bbolt backend's only prerequisite is persistent disk storage. The database
-file will be locked by a single server process at a time, so note that this
-backend will not support things like high availability or zero-downtime
-deployment.
+The bbolt backend's only prerequisite is persistent disk storage. Since a
+single running server locks the database file, this backend won't support high
+availability or zero-downtime deployment.
 
-The bbolt backend is activated by default if no other backends have environment
+The bbolt backend is active by default if no other backends have environment
 variables set. You can set `DB_PATH` to the desired location of the database on
-disk; it defaults to "randomizer.db" in the current directory.
+disk, otherwise it defaults to "randomizer.db" in the current directory.
 
 [bbolt]: https://go.etcd.io/bbolt
 
@@ -62,8 +61,7 @@ this up. You can also reference `GroupsTable` in `CloudFormation.yaml`.
 To activate the DynamoDB backend, set `DYNAMODB_TABLE` to the name of the
 table. You may also need to configure [environment variables for the AWS
 SDK][AWS vars]. (Note that other environment variables associated with DynamoDB
-in the code are unstable; they may be removed or their behavior may change in
-the future.)
+in the code are unstable, and are subject to removal or behavior changes.)
 
 [AWS vars]: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html
 
@@ -72,7 +70,7 @@ the future.)
 Firestore is Google's fully managed document database. This mode is especially
 useful to run `randomizer-server` on [Cloud Run][Cloud Run], with a level of
 operational ease comparable to the AWS Lambda solution (though the randomizer
-does not provide infrastructure-as-code for it out of the box).
+doesn't include infrastructure-as-code for it out of the box).
 
 The Firestore backend requires a pre-existing database in a Google Cloud
 project (only Native mode has been tested, but Datastore mode may work too).
@@ -83,7 +81,8 @@ free tier.
 To activate the Firestore backend, set both of the following variables:
 
 - `FIRESTORE_PROJECT_ID`: The ID (not name) of your Google Cloud project.
-- `FIRESTORE_DATABASE_ID`: The ID of the database to use (e.g. "(default)").
+- `FIRESTORE_DATABASE_ID`: The ID of the database to use (for example,
+  "(default)").
 
 You may also need to configure [Application Default Credentials][ADC] for the
 Google Cloud SDK.