README.md in confuse-0.1.8 vs README.md in confuse-1.0.0

@@ -1,14 +1,17 @@
-# Configuration
+# Confuse
 
-TODO: Write a gem description
+This gem is used to simplify specifying and reading configuration.
 
+You can define what you expect to be configured, and this can be read from ini
+files, yaml files or environment variables.
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'configuration'
+    gem 'confuse'
 
 And then execute:
 
     $ bundle
 
@@ -16,10 +19,115 @@
 
     $ gem install configuration
 
 ## Usage
 
-TODO: Write usage instructions here
+Basic usage:
+
+    config = Confuse.config do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+    config[:foo]
+    config.foo
+
+Types:
+
+You can choose where and your config is stored by passing a :path variable to
+Confuse.config:
+
+    config = Confuse.config :path => 'config.ini' do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+Confuse will attempt to work out the type of file from the extension (Supports
+.ini for ini files, and .yml or .yaml for yaml files). You can override this by
+passing in a :type option:
+
+    config = Confuse.config :path => 'foo.conf' :type => :yaml do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+If no type or path is given, it will default to environment variables.
+
+Environment variables have one extra feature, which is the ability to provide a
+prefix:
+
+
+    config = Confuse.config :prefix => 'FOO' :type => :yaml do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+This means Confuse will lookup environment varialbles with that prefix with an
+underscore followed by the configuration name. If none is given, it will lookup
+environment variables as is.
+
+Namespaces:
+
+You can separate your configuration into different namespaces:
+
+    config = Confuse.config :type => :env do |conf|
+      conf.add_namespace :foo do |ns|
+        ns.add_item :foo, :description => 'Foo', :default => 1
+      end
+    end
+
+For simplicity, you can fetch these items using a single []:
+
+    config[:foo_bar]
+
+Or a method call:
+
+    config.foo_bar
+
+However, beware of adding an item at the top level with the same name.
+
+Check:
+
+If you want to make sure all your configuration items are in place before
+running the program you can call .check on it.
+
+    config = Confuse.config do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+    config.check
+
+If any of the items haven't been set, and don't have a default value, an
+exception will be thrown. If you don't care about certain variables, you can
+pass :required => false to them (or give them a default value).
+
+Use a different source:
+
+If you want to use a source that isn't an ini file or yaml file, or environment
+variable. It is very easy to create your own one. It simply needs to be a class
+that has an initialize that takes a hash, and a [] method that takes a
+namespace and a key argument.
+
+    class MyOwnSource
+      def initialize(options = {})
+        ...
+      end
+
+      def [](namespace, key)
+        ...
+      end
+    end
+
+    Confuse::Source.register(:foo, MyOwnSource)
+
+    definition = Confuse.config, :type => :foo do |conf|
+      conf.add_item :foo
+    end
+
+    config = Confuse::Config.new(definition, my_own_source)
+
+If your class takes a :path variable, it will autodetect the extension for
+whatever you register. You can register more than one extension if you wish.
+
+You could use this to store data in whatever fancy file format you like, or
+perhaps even a database table, or one of those fancy NoSQL datastores, you
+could even write your config in Ruby code.
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)