diff --git a/README.md b/README.md
index 9f68c5d..b376364 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,128 @@
 # YAML support for the Go language
 
-This package is a pure port of the [libyaml](http://pyyaml.org/wiki/LibYAML)
-C library for the Go language.
+Introduction
+------------
 
-The import path for the package is gonuts.org/v1/yaml. To install it, run:
+The yaml package enables Go programs to comfortably encode and decode YAML
+values. It was developed within [Canonical](https://www.canonical.com) as
+part of the [juju](https://juju.ubuntu.com) project, and is based on a
+pure Go port of the well-known [libyaml](http://pyyaml.org/wiki/LibYAML)
+C library to parse and generate YAML data quickly and reliably.
+
+Compatibility
+-------------
+
+The yaml package is almost compatible with YAML 1.1, including support for
+anchors, tags, etc. There are still a few missing bits, such as document
+merging, base-60 floats (huh?), and multi-document unmarshalling. These
+features are not hard to add, and will be introduced as necessary.
+
+Installation and usage
+----------------------
+
+The import path for the package is *gonuts.org/v1/yaml*.
+
+To install it, run:
 
     go get gonuts.org/v1/yaml
 
-If opened in a browser, the import path leads to the API documentation:
+API documentation
+-----------------
+
+If opened in a browser, the import path itself leads to the API documentation:
 
   * [https://gonuts.org/v1/yaml](https://gonuts.org/v1/yaml)
 
+API stability
+-------------
+
 The package API for yaml v1 will remain stable as described in [gonuts.org](https://gonuts.org).
+
+
+License
+-------
+
+The yaml package is licensed under the LGPL with an exception that allows it to be linked statically. Please see the LICENSE file for details.
+
+
+Example
+-------
+
+```Go
+package main
+
+import (
+        "fmt"
+	"log"
+
+        "gonuts.org/v1/yaml"
+)
+
+var data = `
+a: Easy!
+b:
+  c: 2
+  d: [3, 4]
+`
+
+type T struct {
+        A string
+        B struct{C int; D []int ",flow"}
+}
+
+func main() {
+        t := T{}
+    
+        err := yaml.Unmarshal([]byte(data), &t)
+        if err != nil {
+                log.Fatalf("error: %v", err)
+        }
+        fmt.Printf("--- t:\n%v\n\n", t)
+    
+        d, err := yaml.Marshal(&t)
+        if err != nil {
+                log.Fatalf("error: %v", err)
+        }
+        fmt.Printf("--- t dump:\n%s\n\n", string(d))
+    
+        m := make(map[interface{}]interface{})
+    
+        err = yaml.Unmarshal([]byte(data), &m)
+        if err != nil {
+                log.Fatalf("error: %v", err)
+        }
+        fmt.Printf("--- m:\n%v\n\n", m)
+    
+        d, err = yaml.Marshal(&m)
+        if err != nil {
+                log.Fatalf("error: %v", err)
+        }
+        fmt.Printf("--- m dump:\n%s\n\n", string(d))
+}
+```
+
+This example will generate the following output:
+
+```
+--- t:
+{Easy! {2 [3 4]}}
+
+--- t dump:
+a: Easy!
+b:
+  c: 2
+  d: [3, 4]
+
+
+--- m:
+map[a:Easy! b:map[c:2 d:[3 4]]]
+
+--- m dump:
+a: Easy!
+b:
+  c: 2
+  d:
+  - 3
+  - 4
+```
+