diff --git a/README.md b/README.md
index 426c82d..a97cff5 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
+[![GoDoc](https://godoc.org/github.com/alexflint/go-arg?status.svg)](https://godoc.org/github.com/alexflint/go-arg)
+
 ## Structured argument parsing for Go
 
+Declare the command line arguments your program accepts by defining a struct.
+
 ```go
 var args struct {
 	Foo string
@@ -43,8 +47,8 @@ var args struct {
 	Output  []string `arg:"positional"`
 }
 arg.MustParse(&args)
-fmt.Println("Input:", input)
-fmt.Println("Output:", output)
+fmt.Println("Input:", args.Input)
+fmt.Println("Output:", args.Output)
 ```
 
 ```
@@ -102,6 +106,10 @@ Fetching the following IDs from foo: [1 2 3]
 go get github.com/alexflint/go-arg
 ```
 
+### Documentation
+
+https://godoc.org/github.com/alexflint/go-arg
+
 ### Rationale
 
 There are many command line argument parsing libraries for Go, including one in the standard library, so why build another?
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 0000000..d2febf6
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,89 @@
+package arg
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/alexflint/go-arg"
+)
+
+// This example demonstrates basic usage
+func Example_Basic() {
+	// These are the args you would pass in on the command line
+	os.Args = []string{"./example", "--foo=hello", "--bar"}
+
+	var args struct {
+		Foo string
+		Bar bool
+	}
+	arg.MustParse(&args)
+	fmt.Println(args.Foo, args.Bar)
+}
+
+// This example demonstrates arguments that have default values
+func Example_DefaultValues() {
+	// These are the args you would pass in on the command line
+	os.Args = []string{"--help"}
+
+	var args struct {
+		Foo string
+		Bar bool
+	}
+	args.Foo = "default value"
+	arg.MustParse(&args)
+	fmt.Println(args.Foo, args.Bar)
+}
+
+// This example demonstrates arguments that are required
+func Example_RequiredArguments() {
+	// These are the args you would pass in on the command line
+	os.Args = []string{"--foo=1", "--bar"}
+
+	var args struct {
+		Foo string `arg:"required"`
+		Bar bool
+	}
+	arg.MustParse(&args)
+}
+
+// This example demonstrates positional arguments
+func Example_PositionalArguments() {
+	// These are the args you would pass in on the command line
+	os.Args = []string{"./example", "in", "out1", "out2", "out3"}
+
+	var args struct {
+		Input  string   `arg:"positional"`
+		Output []string `arg:"positional"`
+	}
+	arg.MustParse(&args)
+	fmt.Println("Input:", args.Input)
+	fmt.Println("Output:", args.Output)
+}
+
+// This example demonstrates arguments that have multiple values
+func Example_MultipleValues() {
+	// The args you would pass in on the command line
+	os.Args = []string{"--help"}
+
+	var args struct {
+		Database string
+		IDs      []int64
+	}
+	arg.MustParse(&args)
+	fmt.Printf("Fetching the following IDs from %s: %q", args.Database, args.IDs)
+}
+
+// This example shows the usage string generated by go-arg
+func Example_Usage() {
+	// These are the args you would pass in on the command line
+	os.Args = []string{"--help"}
+
+	var args struct {
+		Input    string   `arg:"positional"`
+		Output   []string `arg:"positional"`
+		Verbose  bool     `arg:"-v,help:verbosity level"`
+		Dataset  string   `arg:"help:dataset to use"`
+		Optimize int      `arg:"-O,help:optimization level"`
+	}
+	arg.MustParse(&args)
+}
diff --git a/parse.go b/parse.go
index dfa3421..6e92633 100644
--- a/parse.go
+++ b/parse.go
@@ -1,3 +1,37 @@
+// Package arg parses command line arguments using the fields from a struct.
+// Any exported field is interpreted as a command line option, so
+//
+//    var args struct {
+//	    Iter int
+//      Debug bool
+//   }
+//   arg.MustParse(&args)
+//
+// defines two command line arguments, which can be set using any of
+//
+//    ./example --iter=1 --bar    // bar is a boolean flag so its value is optional
+//    ./example -iter 1           // bar will default to its zero value
+//    ./example --bar=true        // foo will default to its zero value
+//
+// The fastest way to learn how to use go-arg is to read the examples below.
+//
+// Fields can be bool, string, any float type, or any signed or unsigned integer type.
+// They can also be slices of any of the above, or slices of pointers to any of the above.
+//
+// Tags can be specified using the `arg` package name:
+//
+//    var args struct {
+//	    Input string   `arg:"positional"`
+//	    Log string     `arg:"positional,required"`
+//      Debug bool     `arg:"-d,help:turn on debug mode"`
+//      RealMode bool  `arg:"--real"
+//      Wr io.Writer   `arg:"-"`
+//   }
+//
+// The valid tag strings are `positional`, `required`, and `help`. Further, any tag string
+// that starts with a single hyphen is the short form for an argument (e.g. `./example -d`),
+// and any tag string that starts with two hyphens is the long form for the argument
+// (instead of the field name). Fields can be excluded from processing with `arg:"-"`.
 package arg
 
 import (