Merge branch 'master' of github.com:Spawnfest2012/holybrolly-nakaz

README.md

@@ -13,6 +13,7 @@ Yes. And very useful!
 
 What is it for?
 ---------------
+
 For easy and sexy config files processing and easy config reloading support.
 
 Why do I need it?
@@ -25,7 +26,35 @@ Nakaz uses YAML for config files (which is human-readable and clean),
 -record specs as config schema definition, has schema validation and has
 support for config reloading interface and callbacks.
 
+Ho can I use it?
+----------------
+
+(hopefuly) the usage of `nakaz` is pretty straighforward, though you
+still have to keep in mind **two** things:
+
+* `nakaz` uses [YAML] [1] as base configuration format;
+* `nakaz` requires you to structure your [YAML] [1] config in a *special*
+  way, which is described bellow.
+
+The basic configuration unit in `nakaz` is a **section**, which is
+represented as a **named** [mapping] [2] on the YAML side. Each
+configured application can have one or more sections, for example:
+
+```yaml
+example:
+  log_conf:
+    log: "priv/log.txt"
+    severity: debug
+```
+
+Here, [example] [3] application defines a single section, named
+`log_conf`. As you might have noticed, applications are defined
+on the **top level** of the configuration file, with sections,
+residing on the **second level**.
 
+[1]: http://www.yaml.org
+[2]: http://en.wikipedia.org/wiki/YAML#Associative_arrays
+[3]: https://github.com/Spawnfest2012/holybrolly-nakaz/blob/master/example/priv/conf.yaml
 
 Why the name?
 -------------