Add blog post about documentation

sass/custom/_paulus.scss

@@ -333,11 +333,17 @@ p.note {
   font-size: .8em;
 }
 
-ul.sidebar-menu a.active {
-  color: #000;
-  font-weight: bold;
+ul.sidebar-menu {
+  a.active {
+    color: #000;
+    font-weight: bold;
+  }
+
+  ul {
+    margin-left: 30px;
+  }
 }
 
 a code {
   color: #049cdb;
-}
+}

source/_includes/asides/getting_started_navigation.html

@@ -10,7 +10,7 @@
           <li>{% active_link /getting-started/installation-raspberry-pi/ Raspberry Pi %}</li>
           <li>{% active_link /getting-started/installation-docker/ Docker %}</li>
           <li>{% active_link /getting-started/installation-synology/ Synology NAS %}</li>
-          <li>{% active_link /getting-started/installation-virtualenv/ Virtual Environment %}</li>
+          <li>{% active_link /getting-started/installation-virtualenv/ VirtualEnv Linux Instructions %}</li>
           <li>{% active_link /getting-started/troubleshooting/ Troubleshooting %}</li>
         </ul>
       </li>

source/_posts/2014-12-18-website-launched.markdown

@@ -7,7 +7,7 @@ date_formatted: "December 18, 2014"
 author: Paulus Schoutsen
 author_twitter: balloob
 comments: true
-categories: Branding
+categories: Website
 ---
 
 I finally took the time to setup a simple website to help people getting started with Home Assistant. The process was super smooth thanks to the great tools [Jekyll](http://jekyllrb.com) and [Octopress](http://octopress.org) and the great services [GitHub Pages](https://pages.github.com) and [CloudFlare](https://cloudflare.com).

source/_posts/2016-04-17-updated-documentation.markdown

@@ -0,0 +1,26 @@
+---
+layout: post
+title: "Updated documentation"
+description: "We have reorganised our documentation which should make it easier to get started and develop for Home Assistant."
+date: 2016-04-16 23:09:00 -0700
+date_formatted: "April 17, 2016"
+author: Paulus Schoutsen
+author_twitter: balloob
+comments: true
+categories: Website
+---
+
+One of the main complaints that we receive is something along the lines "I read that X is possible yet I am unable to find it on the website.". This post is to announce that we have taken the first steps to improve it by revamping the [getting started] and [developers] sections. It's still a work in progress but we now have a solid foundation to build on for the future 👍.
+
+Our documentation has been going through various phases. Initially it was just the README in our GitHub repository. I discovered Jekyll and GitHub pages in December 2014 and created home-assistant.io. I more or less broke the README in 5 pages and [called it a website]. Back then we had a whopping [11 components](https://github.com/home-assistant/home-assistant.io/blob/86bb2df430ce267ab2123d51592d3f068ae509b5/source/components/index.markdown).
+
+As Home Assistant grew, so did our documentation. [Fabian Affolter](https://github.com/fabaff) does an amazing job in making sure there is at least a documentation stub for each new feature that lands. And that's quite a feat given our [frequent releases](https://home-assistant.io/blog/categories/release-notes/)! But despite all the efforts, the documentation outgrew our existing documentation organisation.
+
+Today it has been almost 1.5 years since we started the website. We now have [264 components and platforms] under our belt and have been honored with 1.5 million pageviews ✨. And hopefully we now also have documentation that our community deserves.
+
+[getting started]: /getting-started/
+[developers]: /developers/
+[called it a website]: /blog/2014/12/18/website-launched/
+[264 components and platforms]: /components/
+
+Finally, if you see some content that could use more clarifcation or is outdated, don't hesitate to use the 'Edit in GitHub' link that is present on each page.

source/developers/index.markdown

@@ -10,3 +10,8 @@ footer: true
 ---
 
 Welcome to the Home Assistant development documentation. This is the place to learn all about how Home Assistant works and how you can extend it with support for your devices and services!
+
+<p class='img'>
+<img src='/images/architecture/component_interaction.png' alt='Diagram showing interaction between components and the Home Assistant core.'>
+Diagram showing interaction between components and the Home Assistant core.
+</p>

source/getting-started/index.markdown

@@ -9,11 +9,11 @@ sharing: true
 footer: true
 ---
 
-Installing and running Home Assistant on your local machine is easy. Make sure you have [Python 3.4 or higher](https://www.python.org/downloads/) installed and execute the following code in a console:
+Below you can find the standard instructions. See the sidebar for installation instructions for specific platforms. If you're running a Linux based platform, we suggest to follow the [VirtualEnv Linux instructions] to avoid having to use root.
 
-<p class='note'>
-It's highly recommended to use a [virtual environment](https://docs.python.org/3.4/library/venv.html) to keep things separated. A virtual environment can be created by exceuting the following command: `python3 -m venv /path/where/you/home-assistant/`. Then change to the created directory and go the next step.
-</p>
+[VirtualEnv Linux instructions]: /getting-started/installation-virtualenv/
+
+Installing and running Home Assistant on your local machine is easy. Make sure you have [Python 3.4 or higher](https://www.python.org/downloads/) installed and execute the following code in a console:
 
 ```bash
 $ pip3 install homeassistant
@@ -25,7 +25,6 @@ Running these commands will:
  - Install Home Assistant
  - Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123)
 
-
 If you prefer to watch a video tutorial, [tktino](https://github.com/tktino) has made some great ones.
 
  - [Windows 10](https://www.youtube.com/watch?v=X27eVvuqwnY)
@@ -49,7 +48,7 @@ If you run into any issues, please see [the troubleshooting page](/getting-start
 In addition to this site, check out these sources for additional help:
 
  - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- - [Gitter Chat Room](https://gitter.im/balloob/home-assistant) for real-time chat about Home Assistant.
+ - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
  - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
 
 ### {% linkable_title What's next %}