README: Document configuration further (#61)

Adds more details on how to configure sally
and what the required and optional fields are.

Also updates the installation instructions
since you can't `go get` the binary anymore.

1 files changed, 49 insertions, 8 deletions

diff --git a/README.md b/README.md
index 4cafea2..ae1888d 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,69 @@
 # sally
 
-A tiny HTTP server for supporting custom Golang import paths
+sally is a small HTTP service you can host
+to serve vanity import paths for Go modules.
 
 ## Installation
 
-`go get go.uber.org/sally`
+```bash
+go install go.uber.org/sally@latest
+```
 
 ## Usage
 
 Create a YAML file with the following structure:
 
 ```yaml
-# This optional section configures godoc documentation linking.
+# sally.yaml
+
+# Configures documentation linking.
+# Optional.
 godoc:
-  # Instance of godoc server used for documentation links. Defaults to pkg.go.dev.
+  # Host for the Go documentation server.
+  # Defaults to pkg.go.dev.
   host: pkg.go.dev
 
-url: google.golang.org
+# Base URL for your package site.
+# If you want your modules available under "example.com",
+# specify example.com here.
+# This field is required.
+url: go.uber.org
+
+# Collection of packages under example.com
+# and their Git repositories.
 packages:
-  grpc:
-    repo: github.com/grpc/grpc-go
+
+  # The key is the name of the package following the base URL.
+  # For example, if you want to make a package available at
+  # "example.com/foo", you'd specify "foo" here.
+  zap:
+    # Path to the Git repository.
+    #
+    # This field is required.
+    repo: github.com/uber-go/zap
+
+    # Branch of the Git repository that you're linking to.
+    #
+    # Defaults to "master".
+    branch: master
+
+    # Alternative base URL instead of the value configured at the top-level.
+    # This is useful if the same sally instance is
+    # hosted behind multiple base URLs.
+    #
+    # Defaults to the value of the top-level url field.
+    url: example.com
+```
+
+Run sally like so:
+
+```shell
+$ sally
 ```
 
-Then run Sally to start the HTTP server:
+This will read from sally.yaml and serve on port 8080.
+To use a different port and/or configuration file,
+use the `-yml` and `-port` flags.
 
 ```
 $ sally -yml site.yaml -port 5000