heroku/schematic — pull request #13 by mmcgrana (2014-04-23 16:24:52+00:00)
Title: Docs suggestions

Per request by @cyberdelia, providing a review of the docs.

Made some minor tweaks in this branch.

When putting on my hat of "I'm an ordinary Go user and I want
to use this library to consume some random Schema-documented
API", the biggest issue that I see is around the custom `http.Client`.
It seems like basically any non-trivial API is going to need something
here, and we currently provide little guidance. Probably the best
resources that we have right now are links to existing custom
implementations for e.g. heroku-go, which I've added in this branch.

I wonder what else we can do to make this easier for users, and more
likely that they'll successfully be able to wire up their generated clients
to the actual APIs?

The other major docs issue is explaining how the various types of
methods work, especially the different patterns for List, Info, Create,
and Update. I think I mostly know how to explain this but would just
need to write it up.

I checked out the godocs build from generated packages and they
look pretty good. One thing they are missing is something in the
Overview section. Maybe we could throw one or two sentences in
there, based on the top-level schema metadata?