diff --git a/Data/Yaml.hs b/Data/Yaml.hs
--- a/Data/Yaml.hs
+++ b/Data/Yaml.hs
@@ -6,6 +6,21 @@
 {-# LANGUAGE PatternGuards #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE OverloadedStrings #-}
+-- | Provides a high-level interface for processing YAML files.
+--
+-- This module reuses most of the infrastructure from the @aeson@ package.
+-- This means that you can use all of the existing tools for JSON
+-- processing for processing YAML files. As a result, much of the
+-- documentation below mentions JSON; do not let that confuse you, it's
+-- intentional.
+--
+-- For the most part, YAML content translates directly into JSON, and
+-- therefore there is very little data loss. If you need to deal with YAML
+-- more directly (e.g., directly deal with aliases), you should use the
+-- "Text.Libyaml" module instead.
+--
+-- For documentation on the @aeson@ types, functions, classes, and
+-- operators, please see the @Data.Aeson@ module of the @aeson@ package.
 module Data.Yaml
     ( -- * Types
       Value (..)
diff --git a/yaml.cabal b/yaml.cabal
--- a/yaml.cabal
+++ b/yaml.cabal
@@ -1,17 +1,23 @@
 name:            yaml
-version:         0.8.1
+version:         0.8.1.1
 license:         BSD3
 license-file:    LICENSE
 author:          Michael Snoyman <michael@snoyman.com>, Anton Ageev <antage@gmail.com>,Kirill Simonov 
 maintainer:      Michael Snoyman <michael@snoyman.com>
-synopsis:        Low-level binding to the libyaml C library.
+synopsis:        Support for parsing and rendering YAML documents.
 description:     Provides support for parsing and emitting Yaml documents.
                  .
                  This package includes the full libyaml C library version 0.1.2 by Kirill
                  Simonov (<http://pyyaml.org/wiki/LibYAML>) in the package so you
                  don't need to worry about any non-Haskell dependencies.
+                 .
+                 The package is broken down into two modules.
+                 "Data.Yaml" provides a high-level interface based
+                 around the JSON datatypes provided by the @aeson@
+                 package. "Text.Libyaml" provides a lower-level,
+                 streaming interface. For most users, "Data.Yaml" is recommended.
 category:        Web
-stability:       unstable
+stability:       stable
 cabal-version:   >= 1.8
 build-type:      Simple
 homepage:        http://github.com/snoyberg/yaml/