Made README and website contributions match, added more detail to website contribution setup details, updated forum link, re-organised getting started and troubleshooting with respect to YAML

source/getting-started/configuration.markdown

@@ -9,19 +9,74 @@ sharing: true
 footer: true
 ---
 
-Home Assistant will create a configuration folder when it is run for the first time. The location of the folder differs between operating systems: on OS X/Linux it's `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`. If you want to use a different folder for configuration, run `hass --config path/to/config`.
+Home Assistant will create a configuration folder when it is run for the first time. The location of the folder differs between operating systems: on OS X and Linux it's `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`. If you want to use a different folder for configuration, run `hass --config path/to/config`.
 
-Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains which components will be loaded and what their configuration is.
-This file contains YAML code, which is explained briefly in [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/). An example configuration file is located [here](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example).
+Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains which components will be loaded and what their configuration is.  
+This file contains YAML code, which is explained briefly below.  
+[An example configuration file is located here](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example).
 
-When launched for the first time, Home Assistant will write a default configuration enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the interface.
+When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the user interface.
 
 If you run into trouble while configuring Home Assistant, have a look at [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/).
 
 <p class='note'>
-You will have to restart Home Assistant for changes in <code>configuration.yaml</code> to take effect.
+  You will have to restart Home Assistant each time you make changes in <code>configuration.yaml</code> in order for these to take effect.
 </p>
 
+### {% linkable_title YAML %}
+
+Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations.
+
+For each component that you want to use in Home Assistant, you add code in your `configuraton.yaml` file to specify its settings.  
+Example, the following code specifies that you want to use the [notify component](/components/notify)  with the [pushbullet platform](/components/notify.pushbullet).  
+
+
+```yaml
+notify:
+  platform: pushbullet
+  api_key: "o.1234abcd"
+  name: pushbullet
+```
+
+- A **component** provides the core logic for some functionality (like `notify` provides sending notifications). 
+- A **platform** makes the connection to a specific software or hardware platform (like `pushbullet` works with the service from pushbullet.com).
+
+The basics of YAML syntax are block collections and mappings containing key-value pairs.  
+Each item in a collection starts with a `-` while mappings have the format `key: value`. If you specify duplicate keys, the last value for a key is used.  
+
+Note that indentation is an important part of specifying relationships using YAML. Things that are indented are nested "inside" things that are one level higher. So in the above example, `platform: pushbullet` is a property of (nested inside) the `notify` component.  
+Getting the right indentation can be tricky if you're not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. Convention is to use 2 spaces for each level of indentation.
+
+Lines that start with **#** are comments and are ignored by the system.
+
+The next example shows an [input_select](/components/input_select) component that uses a block collection for the options values.  
+The other properties (like name) are specified using mappings. Note that the second line just has `threat:` with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it.
+
+```yaml
+input_select:
+  threat:
+    name: Threat level
+# A collection is used for options
+    options:
+     - 0
+     - 1
+     - 2
+     - 3
+    initial: 0
+```
+
+The following example shows nesting a collection of mappings in a mapping.  
+In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their `state_topic` (one of the properties used for MQTT sensors). 
+
+```yaml
+sensor:
+  - platform: mqtt
+    state_topic: sensor/topic
+  - platform: mqtt
+    state_topic: sensor2/topic
+```
+
+
 ### {% linkable_title Setting up the basic info %}
 
 By default Home Assistant will try to detect your location and will automatically select a temperature unit and time zone based on your location. You can overwrite this by adding the following information to your `configuration.yaml`:
@@ -47,7 +102,7 @@ homeassistant:
 
 ### {% linkable_title Password protecting the web interface %}
 
-The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `configuration.yaml` and add the following to the `http` section:
+The first thing you will want to add is a password for the web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section:
 
 ```yaml
 http: