edit readme and amend command descriptions

Author: miparnisari

CONTRIBUTING.md

@@ -3,8 +3,7 @@
 ## Communication
 
 - Issues: [GitHub](https://github.com/authzed/thumper/issues)
-- Email: [Google Groups](https://groups.google.com/g/authzed-oss)
-- Discord: [Zanzibar Discord](https://discord.gg/jTysUaxXzM)
+- Discord: [Discord](https://discord.gg/jTysUaxXzM)
 
 All communication must follow our [Code of Conduct].
 

README.md

@@ -1,57 +1,43 @@
 # Thumper
 
-Thumper is a traffic generator for SpiceDB and Authzed.
-It will issue CheckPermission, Read/Write Relationships, ExpandPermissionTree and LookupResources to a SpiceDB or Authzed endpoint, and exposes Prometheus metrics about those operations.
+Thumper can be used as an artificial traffic generator or/and as an availability probe for [SpiceDB](https://github.com/authzed/spicedb) instances.
 
-## Setting up
+It can issue CheckPermission and CheckBulkPermission requests, Read/Write Relationships, ExpandPermissionTree and LookupResources. It also can expose Prometheus metrics about those operations.
 
-Install thumper
+## Usage
 
-```sh
-git clone https://github.com/authzed/thumper.git
-cd thumper
-go build -o thumper ./cmd/thumper
-sudo mv thumper /usr/local/bin/  # Optional if you want to move thumper into $PATH
-```
-
-Run the migration script required by your thumper scripts against your permission system.
-
-```sh
-thumper migrate --endpoint grpc.authzed.com:443 --token t_some_token ./scripts/schema.yaml
-```
-
-## Running
-
-### Running against an Authzed instance
+1. Install thumper:
 
-```sh
-thumper run --endpoint grpc.authzed.com:443 --token t_some_token ./scripts/example.yaml
-```
-
-### Running against a local SpiceDB
-
-```sh
-thumper run --token presharedkeyhere --insecure ./scripts/example.yaml
-```
+    ```sh
+    git clone https://github.com/authzed/thumper.git
+    cd thumper
+    go build -o thumper ./cmd/thumper
+    sudo mv thumper /usr/local/bin/  # Optional if you want to move thumper into $PATH
+    ```
 
-## Configuring
+1. Write your script in a YAML file (see [script format](#script-format) down below.)
 
-### Changing the QPS
+1. If your script contains schema or relationship writes, run the migration step to set that data up first:
 
-By default, Thumper will run a single goroutine, which will issues calls once per second, at rates configured in [thumperrunner/definitions.go](internal/thumperrunner/definitions.go).
+    ```sh
+    thumper migrate --endpoint grpc.authzed.com:443 --token t_some_token ./scripts/schema.yaml
+    ```
 
-To increase the number of calls issued, the `THUMPER_QPS` environment variable or `--qps` flag can be used:
+1. Run your script as in the following examples:
 
-```sh
-thumper run --token presharedkeyhere --qps 5
-```
+    ```sh
+    # 5 requests per second against Authzed's hosted SpiceDB with a secure connection:
+    thumper run --qps 5 --endpoint grpc.authzed.com:443 --token t_some_token ./scripts/example.yaml
 
-The above will spawn 5 goroutines, which will each issue calls once per second.
+    # 1 request per second against local SpiceDB with an insecure connection:
+    thumper run --token presharedkeyhere --insecure ./scripts/example.yaml
+    ```
 
 ### Script Format
 
-Thumper config files are yaml files with go template preprocessing supported.
-The final yaml generated by the templates must validate with the schema in `schema.yaml`.
+Thumper config files are YAML files. These files support Go template preprocessing supported.
+
+The final YAML generated by the templates must validate with the schema in [schema.yaml](schema.yaml).
 
 #### Example
 

cmd/thumper/main.go

@@ -23,8 +23,8 @@ func main() {
 
 	rootCmd := &cobra.Command{
 		Use:               "thumper",
-		Short:             "The Authzed Load Generator",
-		Long:              "An artificial load generator for managing health and performance of Authzed.",
+		Short:             "SpiceDB Traffic Generator",
+		Long:              "An artificial traffic generator and availability probe.",
 		PersistentPreRunE: cmd.SyncFlagsCmdFunc,
 		PreRunE:           cmd.DefaultPreRunE("thumper"),
 		SilenceUsage:      true,

internal/cmd/migrate.go

@@ -18,7 +18,7 @@ import (
 
 var MigrateCmd = &cobra.Command{
 	Use:   "migrate migration.yaml [migration2.yaml] [migration3.yaml]",
-	Short: "run thumper migration scripts",
+	Short: "run setup scripts",
 	Example: `
 	Run with a single script against a local SpiceDB:
 		thumper migrate ./scripts/schema.yaml --token "testtesttesttest"

internal/cmd/run.go

@@ -33,7 +33,7 @@ var (
 )
 
 func RegisterRunFlags(cmd *cobra.Command) {
-	cmd.Flags().Int("qps", 1, "QPS with which to call authzed")
+	cmd.Flags().Int("qps", 1, "queries per second to generate")
 	cmd.Flags().Duration("step-timeout", 500*time.Millisecond, "maximum time a single step is allowed to run")
 	cmd.Flags().Bool("randomize-starting-step", false, "randomize the starting script step for each worker")
 
@@ -43,7 +43,7 @@ func RegisterRunFlags(cmd *cobra.Command) {
 
 var RunCmd = &cobra.Command{
 	Use:   "run script.yaml [script2.yaml] [script3.yaml]",
-	Short: "run thumper load generator",
+	Short: "run traffic generator",
 	Example: `
 	Run with a single script against a local SpiceDB:
 		thumper run ./scripts/script.yaml --token "testtesttesttest"