Reorganize and improve documentation (#322)

We've been in need of a documentation revamp for a while; a giant FAQ
was never the greatest structure and got worse as it grew. In this
commit I reorganize the documentation. Most of it is just moving around
existing text, but I added some new documentation here and there.

The changes:
- Many of the FAQ questions have moved to several new docs, on the
client/runtime, handling your schema, and various operation types; the
FAQ has answers to a few of the actually most frequent questions, as
well as a few things that didn't fit elsewhere.
- We now have a `docs/README.md` which acts as an index, so we can just
link to `/docs`.
- I lowercased the files that don't need match a GitHub convention, so
it's a bit less yell-y.
- I added documentation on:
  - how we version genqlient (fixes #63)
  - newer options for optional types
  - a bit more on custom scalars and integer types (fixes #128)

Reviewers, you can see what it all looks like together
[here](https://github.com/Khan/genqlient/tree/benkraft.docs-reorg/docs#readme).

Fixes #245.

I have:
- [x] Written a clear PR title and description (above)
- [x] Signed the [Khan Academy CLA](https://www.khanacademy.org/r/cla)
- [x] Added tests covering my changes, if applicable (n/a)
- [x] Included a link to the issue fixed, if applicable
- [x] Included documentation, for new features
- [x] Added an entry to the changelog (n/a)

README.md

@@ -19,7 +19,7 @@ genqlient provides:
 
 ## How do I use genqlient?
 
-You can download and run genqlient the usual way: `go run github.com/Khan/genqlient`.  To set your project up to use genqlient, see the [getting started guide](docs/INTRODUCTION.md), or the [example](example).  For more complete documentation, see the [docs](docs).
+You can download and run genqlient the usual way: `go run github.com/Khan/genqlient`.  To set your project up to use genqlient, see the [getting started guide](docs/introduction.md), or the [example](example).  For more complete documentation, see the [docs](docs).
 
 ## How can I help?
 
@@ -47,6 +47,6 @@ This code works, but it has a few problems:
 - The GraphQL variables aren't type-safe at all; you could have passed `{"id": true}` and again you won't know until runtime!
 - You have to write everything twice, or hide the query in complicated struct tags, or give up what type safety you do have and resort to `interface{}`.
 
-These problems aren't a big deal in a small application, but for serious production-grade tools they're not ideal.  And they 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 and 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 [docs/DESIGN.md](docs/DESIGN.md) for more prior art.)
+These problems aren't a big deal in a small application, but for serious production-grade tools they're not ideal.  And they 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 and 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 the [design note](docs/design.md) for more prior art.)
 
 genqlient fills that gap: you just specify the query, and it generates type-safe helpers, validated against the schema, that make the query.

docs/CHANGELOG.md

@@ -113,9 +113,9 @@ Version 0.3.0 adds several new configuration options, allowing simplification of
 
 ### New features:
 
-- genqlient's types are now safe to JSON-marshal, which can be useful for putting them in a cache, for example.  See the [docs](FAQ.md#-let-me-json-marshal-my-response-objects) for details.
-- The new `flatten` option in the `# @genqlient` directive allows for a simpler form of type-sharing using fragment spreads.  See the [docs](FAQ.md#-shared-types-between-different-parts-of-the-query) for details.
-- The new `for` option in the `# @genqlient` directive allows applying options to a particular field anywhere it appears in the query.  This is especially useful for fields of input types, for which there is otherwise no way to specify options; see the [documentation on handling nullable fields](FAQ.md#-nullable-fields) for an example, and the [`# @genqlient` directive reference](genqlient_directive.graphql) for the full details.
+- genqlient's types are now safe to JSON-marshal, which can be useful for putting them in a cache, for example.  See the [docs](client_config.md#marshaling) for details.
+- The new `flatten` option in the `# @genqlient` directive allows for a simpler form of type-sharing using fragment spreads.  See the [docs](operations.md#sharing-types) for details.
+- The new `for` option in the `# @genqlient` directive allows applying options to a particular field anywhere it appears in the query.  This is especially useful for fields of input types, for which there is otherwise no way to specify options; see the [documentation on handling nullable fields](operations.md#nullable-fields) for an example, and the [`# @genqlient` directive reference](genqlient_directive.graphql) for the full details.
 
 ### Bug fixes:
 

docs/CONTRIBUTING.md

@@ -22,9 +22,9 @@ Pull requests should have:
 - documentation, for new features
 - changelog entries
 
-Pull requests will be squash-merged, so subsequent commit messages may be brief (e.g. "review comments").
+The PR description template will remind you of these. Pull requests will be squash-merged, so subsequent commit messages may be brief (e.g. "review comments").
 
-Large changes should typically be discussed on the issue tracker first, and should ideally be broken up into separate PRs, or failing that, several commits, for ease of reviewing.
+Large changes should typically be discussed on the issue tracker first, and should ideally be broken up into separate PRs, or failing that, several commits, for ease of reviewing. This is especially true of breaking changes; see the [versioning policy](versioning.md) for what we consider breaking.
 
 ## Style
 
@@ -44,11 +44,11 @@ If you update any code-generation logic or templates, even if no new tests are n
 
 ## Finding your way around
 
-If you're new to genqlient, start out by reading the source of `generate.Generate`, whose comments describe most of the high-level operation of genqlient.  In general, the code is documented inline, often with an introductory comment at the top of the file.  See [DESIGN.md](DESIGN.md) for documentation of major design decisions, which is a good way to get a sense of why genqlient is structured the way it is.
+If you're new to genqlient, start out by reading the source of `generate.Generate`, whose comments describe most of the high-level operation of genqlient.  In general, the code is documented inline, often with an introductory comment at the top of the file.  See the [design note](design.md) for documentation of major design decisions, which is a good way to get a sense of why genqlient is structured the way it is.
 
 ## Making a release
 
-We try to cut releases periodically. To make a release:
+See the [versioning strategy](versioning.md) for when to make a release. To make a release:
 
 - Scan PRs since the last release to check we didn't miss anything in the changelog.
 - Check if there are any regressions or major problems with new features we want to fix before cutting the release.