Improve Readme

README.md

@@ -1,5 +1,13 @@
-BetterSettings [![Gem Version](https://img.shields.io/gem/v/better_settings.svg?colorB=e9573f)](https://rubygems.org/gems/better_settings) [![Build Status](https://travis-ci.org/ElMassimo/better_settings.svg)](https://travis-ci.org/ElMassimo/better_settings) [![Coverage Status](https://coveralls.io/repos/github/ElMassimo/better_settings/badge.svg?branch=master)](https://coveralls.io/github/ElMassimo/better_settings?branch=master) [![Inline docs](http://inch-ci.org/github/ElMassimo/better_settings.svg)](http://inch-ci.org/github/ElMassimo/better_settings) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ElMassimo/better_settings/blob/master/LICENSE.txt)
-=======================================
+<h1 align="center">
+Better Settings
+<p align="center">
+<a href="https://travis-ci.org/ElMassimo/better_settings"><img alt="Build Status" src="https://travis-ci.org/ElMassimo/better_settings.svg"/></a>
+<a href="https://coveralls.io/github/ElMassimo/better_settings?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/ElMassimo/better_settings/badge.svg?branch=master"/></a>
+<a href="http://inch-ci.org/github/ElMassimo/better_settings"><img alt="Inline docs" src="http://inch-ci.org/github/ElMassimo/better_settings.svg"/></a>
+<a href="https://rubygems.org/gems/better_settings"><img alt="Gem Version" src="https://img.shields.io/gem/v/better_settings.svg?colorB=e9573f"/></a>
+<a href="https://github.com/ElMassimo/better_settings/blob/master/LICENSE.txt"><img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/></a>
+</p>
+</h1>
 
 A robust settings library that can read YML files and provide an immutable object allowing to access settings through method calls. Can be used in __any Ruby app__, __not just Rails__.
 
@@ -61,38 +69,42 @@ production:
 
 #### 3. Access your settings
 
-  >> Rails.env
-  => "development"
+```
+>> Rails.env
+=> "development"
 
-  >> Settings.mailer
-  => "#<Settings ... >"
+>> Settings.mailer
+=> "#<Settings ... >"
 
-  >> Settings.mailer.root
-  => "www.example.com
+>> Settings.mailer.root
+=> "www.example.com
 
-  >> Settings.port
-  => 3000
+>> Settings.port
+=> 3000
 
-  >> Settings.dynamic
-  => "Did you know you can use ERB inside the YML file? Env is development."
+>> Settings.dynamic
+=> "Did you know you can use ERB inside the YML file? Env is development."
+```
 
 You can use these settings anywhere, for example in a model:
 
-  class Post < ActiveRecord::Base
-    self.per_page = Settings.pagination.posts_per_page
-  end
+```ruby
+class Post < ActiveRecord::Base
+  self.per_page = Settings.pagination.posts_per_page
+end
+```
 
 ### Advanced Setup ⚙
-Name it `Settings`, name it `Config`, name it whatever you want. Add as many or as few as you like, read from as many files as necessary (nested keys will be merged).
+Name it _Settings_, name it _Config_, name it whatever you want. Add as many or as few as you like, read from as many files as necessary (nested keys will be merged).
 
-We usually read a few optional files for the `development` and `test` environment, which allows each developer to override some settings in their own local environment (we git ignore `development.yml` and `test.yml`).
+We usually read a few optional files for the _development_ and _test_ environments, which allows each developer to override some settings in their own local environment (we git ignore `development.yml` and `test.yml`).
 
 ```ruby
 # app/models/settings.rb
 class Settings < BetterSettings
-  source Rails.root.join('config', 'application.yml'), namespace: Rails.env
-  source Rails.root.join('config', 'development.yml'), namespace: Rails.env, optional: true if Rails.env.development?
-  source Rails.root.join('config', 'test.yml'), namespace: Rails.env, optional: true if Rails.env.test?
+  source "#{ Rails.root }/config/application.yml", namespace: Rails.env
+  source "#{ Rails.root }/config/development.yml", namespace: Rails.env, optional: true if Rails.env.development?
+  source "#{ Rails.root }/config/test.yml", namespace: Rails.env, optional: true if Rails.env.test?
 end
 ```
 Our `application.yml` looks like this:
@@ -128,10 +140,11 @@ A developer might want to override some settings by defining a `development.yml`
 development:
   auto_logout: true
 ````
-The main advantage is that those changes won't be tracked by source control :smiley:
+The main advantage is that those changes won't be tracked in source control :smiley:
 
 ## Opinionated Design
 After using [settingslogic](https://github.com/settingslogic/settingslogic) for a long time, we learned some lessons, which are distilled in the following decisions:
 - __Immutability:__ Once created settings can't be modified.
+- __Fail-Fast:__ Settings are eagerly loaded when `source` is called.
 - __No Optional Setings:__ Any optional setting can be modeled in a safer way, this library doesn't allow them.
 - __Not Tied to a Source File:__ Useful to create multiple environment-specific files.