diff --git a/README.md b/README.md
index 1082b00..d3b5d94 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,23 @@
-docopt.go
+docopt-go
 =========
 
 [![Build Status](https://travis-ci.org/docopt/docopt.go.svg?branch=master)](https://travis-ci.org/docopt/docopt.go)
 
-Golang implementation of [docopt](http://docopt.org/) 0.6.1+fix
+An implementation of [docopt](http://docopt.org/) in the
+[Go](http://golang.org/) programming language.
 
-## Installation
+**docopt** helps you create *beautiful* command-line interfaces easily:
 
-import "github.com/docopt/docopt-go" and then run `go get`.
-
-## API
-
-``` go
-func docopt.Parse(doc string, argv []string, help bool, version string, optionsFirst bool)
-(args map[string]interface{}, err error)
-```
-
-Parse `argv` based on command-line interface described in `doc`.
-
-docopt creates your command-line interface based on its description that you pass as `doc`. Such description can contain --options, <positional-argument>, commands, which could be [optional], (required), (mutually | exclusive) or repeated...
-
-### arguments
-
-`doc` Description of your command-line interface.
-
-`argv` Argument vector to be parsed. os.Args[1:] is used if nil.
-
-`help` Set to false to disable automatic help on -h or --help options..
-
-`version` If set to something besides an empty string, the string will be printed
- if --version is in argv.
-
-`optionsFirst` Set to true to require options precede positional arguments,
- i.e. to forbid options and positional arguments intermix..
-
-### return values
-
-`args`, map[string]interface{}. A map, where keys are names of command-line elements such as e.g. "--verbose" and "<path>", and values are the  parsed values of those elements. interface{} can be `bool`, `int`, `string`, `[]string`.
-
-`err`, error. Either *docopt.LanguageError, *docopt.UserError or nil
-
-## Example
-
-``` go
+```go
 package main
 
 import (
-    "fmt"
-    "github.com/docopt/docopt-go"
+	"fmt"
+	"github.com/docopt/docopt-go"
 )
 
 func main() {
-usage := `Naval Fate.
+	  usage := `Naval Fate.
 
 Usage:
   naval_fate ship new <name>...
@@ -68,15 +34,50 @@
   --moored      Moored (anchored) mine.
   --drifting    Drifting mine.`
 
-    arguments, _ := docopt.Parse(usage, nil, true, "Naval Fate 2.0", false)
-    fmt.Println(arguments)
+	  arguments, _ := docopt.Parse(usage, nil, true, "Naval Fate 2.0", false)
+	  fmt.Println(arguments)
 }
 ```
 
+**docopt** parses command-line arguments based on a help message. Don't
+write parser code: a good help message already has all the necessary
+information in it.
+
+## Installation
+
+⚠ Use the alias “docopt-go”. To use docopt in your Go code:
+
+```go
+import "github.com/docopt/docopt-go"
+```
+
+To install docopt according to your `$GOPATH`:
+
+```console
+$ go get github.com/docopt/docopt-go
+```
+
+## API
+
+```go
+func Parse(doc string, argv []string, help bool, version string,
+    optionsFirst bool, exit ...bool) (map[string]interface{}, error)
+```
+Parse `argv` based on the command-line interface described in `doc`.
+
+Given a conventional command-line help message, docopt creates a parser and
+processes the arguments. See
+https://github.com/docopt/docopt#help-message-format for a description of the
+help message format. If `argv` is `nil`, `os.Args[1:]` is used.
+
+docopt returns a map of option names to the values parsed from `argv`, and an
+error or `nil`.
+
 ## Testing
 
-All tests from the python version have been implemented and all are passing.
+All tests from the Python version are implemented and passing
+at [Travis CI](https://travis-ci.org/docopt/docopt.go). New
+language-agnostic tests have been added
+to [test_golang.docopt](test_golang.docopt).
 
-New language agnostic tests have been added to `test_golang.docopt`.
-
-To run them use `go test`.
+To run tests for docopt-go, use `go test`.
diff --git a/docopt.go b/docopt.go
index e513ae5..c44a123 100644
--- a/docopt.go
+++ b/docopt.go
@@ -1,12 +1,14 @@
 // Licensed under terms of MIT license (see LICENSE-MIT)
 // Copyright (c) 2013 Keith Batten, kbatten@gmail.com
 
-// Package docopt creates beautiful command-line interfaces based on the
-// command help message
-//
-// Port of docopt for python
-// https://github.com/docopt/docopt
-// http://docopt.org
+/*
+Package docopt parses command-line arguments based on a help message.
+
+⚠ Use the alias “docopt-go”:
+	import "github.com/docopt/docopt-go"
+or
+	$ go get github.com/github/docopt-go
+*/
 package docopt
 
 import (
@@ -18,73 +20,28 @@
 	"unicode"
 )
 
-// Parse `argv` based on command-line interface described in `doc`.
-//
-// docopt creates your command-line interface based on its
-// description that you pass as `doc`. Such description can contain
-// --options, <positional-argument>, commands, which could be
-// [optional], (required), (mutually | exclusive) or repeated...
-//
-// Parameters:
-//  doc : string
-//   Description of your command-line interface.
-//
-//  argv : list of string or nil
-//   Argument vector to be parsed. os.Args[1:] is used if nil.
-//
-//  help : bool (default: true)
-//   Set to false to disable automatic help on -h or --help options.
-//
-//  version : string
-//   If set to something besides an empty string, the string will be printed
-//   if --version is in argv
-//
-//  optionsFirst : bool (default: false)
-//   Set to true to require options precede positional arguments,
-//   i.e. to forbid options and positional arguments intermix.
-//
-// Returns:
-//  args : map[string]interface{}
-//   A map, where keys are names of command-line elements
-//   such as e.g. "--verbose" and "<path>", and values are the
-//   parsed values of those elements.
-//
-//  err : error, *docopt.LanguageError, *docopt.UserError
-//
-//  os.Exit on user error or help
-//
-// Example:
-//  package main
-//
-//  import (
-//      "fmt"
-//      "github.com/docopt/docopt-go"
-//  )
-//
-//  func main() {
-//      doc := `
-//  Usage:
-//    my_program tcp <host> <port> [--timeout=<seconds>]
-//    my_program serial <port> [--baud=<n>] [--timeout=<seconds>]
-//    my_program (-h | --help | --version)
-//
-//  Options:
-//    -h, --help Show this screen and exit.
-//    --baud=<n> Baudrate [default: 9600]
-//  `
-//      argv := []string{"tcp", "127.0.0.1", "80", "--timeout", "30"}
-//      fmt.Println(docopt.Parse(doc, argv, true, "", false))
-//  }
-//
-// Example output:
-//  {"--baud": "9600",
-//   "--help": false,
-//   "--timeout": "30",
-//   "--version": false,
-//   "<host>": "127.0.0.1",
-//   "<port>": "8"',
-//   "serial": false,
-//   "tcp": true}
+/*
+Parse `argv` based on the command-line interface described in `doc`.
+
+Given a conventional command-line help message, docopt creates a parser and
+processes the arguments. See
+https://github.com/docopt/docopt#help-message-format for a description of the
+help message format. If `argv` is `nil`, `os.Args[1:]` is used.
+
+docopt returns a map of option names to the values parsed from `argv`, and an
+error or `nil`.
+
+Set `help` to `false` to disable automatic help messages on `-h` or `--help`.
+If `version` is a non-empty string, it will be printed when `--version` is
+specified. Set `optionsFirst` to `true` to require that options always come
+before positional arguments; otherwise they can overlap.
+
+By default, docopt calls `os.Exit(0)` if it handled a built-in option such as
+`-h` or `--version`. If the user errored with a wrong command or options,
+docopt exits with a return code of 1. To stop docopt from calling `os.Exit()`
+and to handle your own return codes, pass an optional last parameter of `false`
+for `exit`.
+*/
 func Parse(doc string, argv []string, help bool, version string,
 	optionsFirst bool, exit ...bool) (map[string]interface{}, error) {
 	// if "false" was the (optional) last arg, don't call os.Exit()
@@ -94,11 +51,13 @@
 	}
 	args, output, err := parse(doc, argv, help, version, optionsFirst)
 	if _, ok := err.(*UserError); ok {
+		// the user gave us bad input
 		fmt.Println(output)
 		if exitOk {
 			os.Exit(1)
 		}
 	} else if len(output) > 0 && err == nil {
+		// the user asked for help or `--version`
 		fmt.Println(output)
 		if exitOk {
 			os.Exit(0)
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 0000000..b87a149
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,37 @@
+package docopt
+
+import (
+	"fmt"
+	"sort"
+)
+
+func ExampleParse() {
+	usage := `Usage:
+  config_example tcp [<host>] [--force] [--timeout=<seconds>]
+  config_example serial <port> [--baud=<rate>] [--timeout=<seconds>]
+  config_example -h | --help | --version`
+	// parse the command line `comfig_example tcp 127.0.0.1 --force`
+	argv := []string{"tcp", "127.0.0.1", "--force"}
+	arguments, _ := Parse(usage, argv, true, "0.1.1rc", false)
+	// sort the keys of the arguments map
+	var keys []string
+	for k := range arguments {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	// print the argument keys and values
+	for _, k := range keys {
+		fmt.Printf("%9s %v\n", k, arguments[k])
+	}
+	// output:
+	//    --baud <nil>
+	//   --force true
+	//    --help false
+	// --timeout <nil>
+	// --version false
+	//        -h false
+	//    <host> 127.0.0.1
+	//    <port> <nil>
+	//    serial false
+	//       tcp true
+}