fill out readme and other docs a bit more

CONTRIBUTING.md

@@ -39,6 +39,10 @@ again.
   1. Go makes it very simple to ensure properly formatted code, so always run
      `go fmt` on your code before committing it.
 
+  1. Any significant changes should almost always be accompanied by tests.  The
+     project already has good test coverage, so look at some of the existing
+     tests if you're unsure how to go about it.
+
   1. Do your best to have [well-formed commit messages][] for each change.
      This provides consistency throughout the project, and ensures that commit
      messages are able to be formatted properly by various git tools.

README.md

@@ -1,10 +1,75 @@
-# go-github
+# go-github #
 
 go-github is Go library for accessing the [GitHub API][].
 
+**Documentation:** <http://godoc.org/github.com/google/go-github>  
+
+
+## Usage ##
+
+Construct a new GitHub client, then use the various services on the client to
+access different parts of the GitHub API.  For example, list all organizations
+for user "willnorris":
+
+```go
+client := github.NewClient(nil)
+orgs, err := client.Organizations.List("willnorris", nil)
+```
+
+Some API methods have optional parameters than can be passed.  For example,
+list recently updated repositories for org "github":
+
+```go
+client := github.NewClient(nil)
+opt := &github.RepositoryListByOrgOptions{Sort: "updated"}
+repos, err := client.Repositories.ListByOrg("github", opt)
+```
+
+The go-github library does not directly handle authentication.  Instead, when
+creating a new client, pass an `http.Client` than can handle authentication for
+you.  The easiest, and recommended, way to do this is using the [goauth2][]
+library, but you can of course use any other library that provides an
+`http.Client`.  For example, to use the goauth2 library with an existing OAuth
+access token:
+
+```go
+t := &oauth.Transport{
+  Config: &oauth.Config{},
+  Token: &oauth.Token{AccessToken: "..."}
+}
+
+client := github.NewClient(t.Client())
+
+// list all repositories for the authenticated user
+repos, err := client.Repositories.List(nil)
+```
+
+See the [goauth2 docs][] for complete instructions on using that library.
+
+Also note that when using an authenticated Client, all calls made by the client
+will include the specified OAuth token. Therefore, authenticated clients should
+almost never be shared between different users.
+
 [GitHub API]: http://developer.github.com/v3/
+[goauth2]: https://code.google.com/p/goauth2/
+[goauth2 docs]: http://godoc.org/code.google.com/p/goauth2/oauth
+
+
+## Roadmap ##
+
+This library is being initially developed for an internal application at
+Google, so API methods will likely be implemented in the order that they are
+needed by that application.  You can track the status of implementation in
+[this Google spreadsheet][].  Eventually, I would like to cover the entire
+GitHub API, so contributions are of course [always welcome][].  The calling
+pattern is pretty well established, so adding new methods is relatively
+straightforward.
+
+[this Google spreadhsheet]: https://docs.google.com/spreadsheet/ccc?key=0ApoVX4GOiXr-dGNKN1pObFh6ek1DR2FKUjBNZ1FmaEE&usp=sharing
+[always welcome]: CONTRIBUTING.md
+
 
-## License
+## License ##
 
 This library is distributed under the BSD-style license found in the LICENSE
 file.

examples/example.go

@@ -10,6 +10,7 @@ func main() {
 	client := github.NewClient(nil)
 
 	fmt.Println("Recently updated repositories owned by user willnorris:")
+
 	opt := &github.RepositoryListOptions{Type: "owner", Sort: "updated", Direction: "desc"}
 	repos, err := client.Repositories.List("willnorris", opt)
 	if err != nil {
@@ -21,8 +22,7 @@ func main() {
 	rate, err := client.RateLimit()
 	if err != nil {
 		fmt.Printf("Error fetching rate limit: %#v\n\n", err)
-		return
+	} else {
+		fmt.Printf("API Rate Limit: %#v\n\n", rate)
 	}
-
-	fmt.Printf("API Rate Limit: %#v\n\n", rate)
 }

github.go

@@ -38,6 +38,10 @@ capable http.Client:
 	// list all repositories for the authenticated user
 	repos, err := client.Repositories.List(nil)
 
+Note that when using an authenticated Client, all calls made by the client will
+include the specified OAuth token. Therefore, authenticated clients should
+almost never be shared between different users.
+
 The full GitHub API is documented at http://developer.github.com/v3/.
 */
 package github