general pass of README cleanup

README.md

@@ -19,41 +19,49 @@ client.Query(context.Background(), &query, nil)
 fmt.Println(query.Me.Name)
 // Output: Luke Skywalker
 ```
-While your code is in principle type-safe, there's nothing to check that the schema looks like you expect it to.  In fact, perhaps here we're querying the GitHub API, in which the field is called `viewer`, not `me`, so this query will fail.  Even more common than misusing the name of the field is mis-capitalizing it: the GraphQL convention is `myUrl` whereas the Go convention is `MyURL`, and it's easy to forget or mistype the struct tag.  (Even if you get it right, it adds up to a lot of handwritten boilerplate!)  Other clients, such as [machinebox/graphql](https://github.com/machinebox/graphql), have even fewer guardrails to help you make the right query and use the result correctly.  This isn't a big deal in a small application, but for serious production-grade tools it's not ideal.
+While this code may seem type-safe, and at the Go level it is, there's nothing to check that the schema looks like you expect it to.  In fact, perhaps here we're querying the GitHub API, in which the field is called `viewer`, not `me`, so this query will fail.  More common than misusing the name of the field is mis-capitalizing it, since Go and GraphQL have somewhat different conventions there.  And even if you get it right, it adds up to a lot of handwritten boilerplate!  And that's the best case; other clients, such as [machinebox/graphql](https://github.com/machinebox/graphql), have even fewer guardrails to help you make the right query and use the result correctly.  This isn't a big deal in a small application, but for serious production-grade tools it's not ideal.
 
-These problems should be entirely avoidable: GraphQL and Go are both typed languages; and GraphQL servers expose their schema in a standard, machine-readable format.  We should be able to simply write a query `{ viewer { name } }`, have that automatically validated against the schema and turned into a Go struct which we can use in our code.  In fact, there's already good prior art to do this sort of thing: [99designs/gqlgen](https://github.com/99designs/gqlgen) is a popular server library that does exactly this: it generates type-safe GraphQL resolvers from a schema.
+These problems should be entirely avoidable: GraphQL and Go are both typed languages; and GraphQL servers expose their schema in a standard, machine-readable format.  We should be able to simply write a query `{ viewer { name } }`, have that automatically validated against the schema and turned into a Go struct which we can use in our code.  In fact, there's already good prior art to do this sort of thing: [99designs/gqlgen](https://github.com/99designs/gqlgen) is a popular server library that generates types, and Apollo has a [codegen tool](https://www.apollographql.com/docs/devtools/cli/#supported-commands) to generate similar client-types for several other languages.  (See [DESIGN.md](DESIGN.md) for more prior art.)
 
-This is a proof-of-concept of a GraphQL client that does the same sort of thing: you specify the query, and it generates type-safe helpers that make your query.
+This is a GraphQL client that does the same sort of thing: you specify the query, and it generates type-safe helpers that make your query.
 
 ## Usage
 
+### Example
+
+To use genqlient, put your GraphQL schema (in [SDL format](https://www.apollographql.com/blog/three-ways-to-represent-your-graphql-schema-a41f4175100d/#0c31)) in a file `schema.graphql`, and put a query like the following in `queries.graphql`:
+
 ```graphql
 # queries.graphql
 query getViewer {
   viewer {
-    MyName: name
+    name
   }
 }
 ```
 
+Then run genqlient (`go run github.com/Khan/genqlient`), and it will generate:
+
 ```go
 // generated.go (auto-generated):
 type getViewerResponse struct { ... }
 func getViewer(ctx context.Context, client *graphql.Client) (*getViewerResponse, error) { ... }
+```
 
+Finally, write your code to call genqlient, like so:
+
+```go
 // your code (error handling omitted for brevity)
-graphqlClient := graphql.NewClient("https://example.com/graphql", http.DefaultClient)
+graphqlClient := graphql.NewClient("https://example.com/graphql", nil)
 viewerResp, _ := getViewer(context.Background(), graphqlClient)
 fmt.Println("you are", viewerResp.Viewer.MyName)
 
 //go:generate go run github.com/Khan/genqlient
 ```
 
-For a complete working example, see `example/`.  For configuration options, see `go doc github.com/Khan/genqlient/generate.Config`.
+For a complete working example, see [`example/`](example).  For configuration options, see [`go doc github.com/Khan/genqlient/generate.Config`](https://pkg.go.dev/github.com/Khan/genqlient/generate#Config).
 
-TODO: document this a bit more, including different ways to specify queries, options once we have those, etc.
-
-## Documentation for generated code
+### Documentation for generated code
 
 For each GraphQL operation (query or mutation), genqlient generates a Go function with the exact same name, which accepts:
 - a `context.Context` (unless configured otherwise)
@@ -62,9 +70,13 @@ For each GraphQL operation (query or mutation), genqlient generates a Go functio
 
 It returns a pointer to a struct representing the query-result, and an `error`.  The struct will always be initialized (never nil), even on error.  The error may be a `github.com/vektah/gqlparser/v2/gqlerror.List`, if it was a GraphQL-level error (in this case the returned struct may still contain useful data, if the API returns data even on error), or may be another error if, for example, the whole HTTP request failed (in which case the struct is unlikely to contain useful data).  If the GraphQL operation has a comment immediately above it, that comment text will be used as the GoDoc for the generated function.
 
-TODO: document generated types further, especially if they become customizable.
+TODO: document generated types further, especially when they become customizable.
 
-## Tests
+## Development
+
+If you'd like to contribute to genqlient, welcome!  The library is still in a somewhat rough state, so please contact us (via an issue or email) before sending a PR.  We'll be ready for the rest of the world soon!
+
+### Tests
 
 `go test ./...` tests code generation.  (This is run by GitHub Actions.)  Most of the tests are snapshot-based; see `generate/generate_test.go`.
 
@@ -72,13 +84,12 @@ TODO: document generated types further, especially if they become customizable.
 
 TODO(benkraft): Figure out how to get GitHub Actions a token to run the example.
 
-## Design
+### Design
 
 See [DESIGN.md](DESIGN.md) for documentation of major design decisions in this library.
 
-## Major TODOs
+### Major TODOs
 
-(*) denotes things we need to use this in prod at Khan
 (+) denotes things we further need before recommending anyone else use this in prod
 
 Generated code:

example/README.md

@@ -20,14 +20,6 @@ It's already checked in to github, but to generate `generated.go`:
 go generate ./...
 ```
 
-## Generating the schema files
+## Generating the schema file
 
-These are also checked in, but to update them:
-
-```sh
-npm install -g graphql-introspection-json-to-sdl
-curl -H "Authorization: bearer <your token>" https://api.github.com/graphql >example/schema.json
-graphql-introspection-json-to-sdl example/schema.json >example/schema.graphql
-```
-
-TODO: something better
+The schema file is also checked in, but to update it, download from the [GitHub API documentation](https://docs.github.com/en/graphql/overview/public-schema).