dominictarr · dominictarr · Jan 16, 2014 · Dec 26, 2013 · Dec 26, 2013 · Dec 26, 2013
diff --git a/README.md b/README.md
@@ -2,25 +2,39 @@
 
 The non-configurable configuration loader for lazy people.
 
-# Usage
+## Usage
 
 The only option is to pass rc the name of your app, and your default configuration.
 
-```
-var rc = require('rc')(appname, {
+```javascript
+var conf = require('rc')(appname, {
   //defaults go here.
-  port: 2468
-})
+  port: 2468,
+
+  //defaults which are objects will be merged, not replaced
+  views: {
+    engine: 'jade'
+  }
+});
+```
+
+`rc` will return your configuration options merged with the defaults you specify.
+If you pass in a predefined defaults object, it will be mutated:
+
+```javascript
+var conf = {};
+require('rc')(appname, conf);
 ```
 
-# Standards
+
+## Standards
 
 Given your application name (`appname`), rc will look in all the obvious places for configuration.
 
   * command line arguments (parsed by optimist)
   * environment variables prefixed with `${appname}_`
   * if you passed an option `--config file` then from that file
-  * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc. 
+  * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc.
   * `$HOME/.${appname}rc`
   * `$HOME/.${appname}/config`
   * `$HOME/.config/${appname}`
@@ -30,14 +44,82 @@ Given your application name (`appname`), rc will look in all the obvious places
   * the defaults object you passed in.
 
 All configuration sources that were found will be flattened into one object,
-so that sources earlier in this list override later ones.
+so that sources **earlier** in this list override later ones.
+
+
+## Configuration File Formats
+
+Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format.  rc ignores file extensions of configuration files.  The example configurations below are equivalent:
+
+
+#### Formatted as `ini`
+
+```
+; You can include comments in `ini` format if you want.
+
+dependsOn=0.10.0
+
+
+; `rc` has built-in support for ini sections, see?
+
+[commands]
+  www     = ./commands/www
+  console = ./commands/repl
+
+
+; You can even do nested sections
+
+[generators.options]
+  engine  = ejs
+
+[generators.modules]
+  new     = generate-new
+  engine  = generate-backend
+
+```
+
+#### Formatted as `json`
+
+```json
+{
+  "dependsOn": "0.10.0",
+  "commands": {
+    "www": "./commands/www",
+    "console": "./commands/repl"
+  },
+  "generators": {
+    "options": {
+      "engine": "ejs"
+    },
+    "modules": {
+      "new": "generate-new",
+      "backend": "generate-backend"
+    }
+  }
+}
+```
+
+
+> Since ini, and env variables do not have a standard for types, your application needs be prepared for strings.
+
+
+
+## Advanced Usage
+
+#### Pass in your own `argv`
+
+You may pass in your own `argv` as the third argument to `rc`.  This is in case you want to [use your own command-line opts parser](https://github.com/dominictarr/rc/pull/12).
+
+```javascript
+require('rc')(appname, defaults, customArgvParser);
+```
+
+
+## Note on Performance
 
-# Formats
+`rc` is running `fs.statSync`-- so make sure you don't use it in a hot code path (e.g. a request handler) 
 
-Configuration files may be in either `json` or `ini` format.
-Since ini, and env variables do not have a standard for types,
-your application needs be prepared for strings.
 
-# License
+## License
 
 BSD / MIT / Apache2