This is a long-standing issue, and I'd really like for us to fix it.

The text in the package description in the godoc and in README.md has diverged. Each one describes and provides examples/documentations for certain things that the other doesn't, and vice versa.

• https://godoc.org/github.com/google/go-github/github
• https://github.com/google/go-github/blob/master/README.md#readme

This means it's harder to read that documentation, since you either need to consult both sources (that have a lot of overlap), or read only one and potentially miss out on something.

It also makes it harder to contribute improvements and changes to the documentation, since there are 2 places, it's unclear which one should be contributed to.

We should fix that by taking the best parts from each document and combine them into a single one. Then we can decide to move forward with one of these options:

• Keep both places for docs and manually keep them in sync.
  • This is where my vote goes.
• Remove most of README details and have it point to godoc.org documentation.
  • I would be okay with this option too.
• Remove most of godoc package documentation and keep the documentation only in README.md.
  • I would be strongly opposed to this option. It wouldn't be in spirit of Go to do that.
• Create/use some tool to generate README.md from the package documentation, make it so README.md is generated via go generate.

  • I don't think it's worth the effort here. The package docs don't change that often, so keeping it in sync manually is not very hard after we make the two texts identical.

    That said, I'll point out that the starting point of most of my Go repo README.md files is generated with gorepogen which does something like that, and it's very easy to extract the package documentation with go/doc.