Sync doc.go and README.md

[gmlewis]

Fixes #397.

Change-Id: I30ce336e3a36cf5758b9bf52b9dd77f7c1df5f27

[dmitshur]

This is so great! Thanks for doing this @gmlewis!

LGTM.

[dmitshur]

I think we should remove the mention of https://github.com/sourcegraph/apiproxy here.

That repository does not compile successfully for over a year now (see sourcegraph/apiproxy#1).

We've stopped using it and supporting it because it turned out that just using https://github.com/gregjones/httpcache for standards-compliant HTTP caching is good enough in most cases.

[gmlewis]

How does that last sentence sound now?

[dmitshur]

go-github does not handle conditional requests directly, but is
instead designed to work with a caching http.Transport. We recommend using
https://github.com/gregjones/httpcache, which can be used to provide additional
flexibility and control of caching rules.

I don't think that sounds right. It makes it sound like gregjones/httpcache is used to provide flexibility and control over caching rules, but in fact that package is what provides actual HTTP client-side caching. That phrase previously applied to apicache, which indeed did provide customization over http caching rules.

I think it should be more like this:

go-github does not handle conditional requests directly, but is
instead designed to work with a caching http.Transport. We recommend using
https://github.com/gregjones/httpcache for that.