Improved README.
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
+```
+
