diff --git a/source/developers/development_environment.markdown b/source/developers/development_environment.markdown
index d4a2891950f..0ca74d82030 100644
--- a/source/developers/development_environment.markdown
+++ b/source/developers/development_environment.markdown
@@ -11,27 +11,15 @@ footer: true
 
 You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up.
 
-### {% linkable_title Setup Local Repository %}
+### {% linkable_title Preparing your environment %}
 
-Visit the [Home Assistant repository](https://github.com/home-assistant/home-assistant) and click **Fork**.
-Once forked, setup your local copy of the source using the commands:
-```bash
-$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
-$ cd home-assistant
-$ git remote add upstream https://github.com/home-assistant/home-assistant.git
-```
-
-### {% linkable_title Prepare Your Environment %}
-
-#### {% linkable_title Core dependencies %} 
+#### {% linkable_title Developing on Linux %}
 
 Install the core dependencies.
 ```bash
-$ sudo apt-get install python3-pip python3-dev
+$ sudo apt-get install python3-pip python3-dev python3-venv
 ```
 
-#### {% linkable_title Platform dependencies %} 
-
 In order to run `script/setup` below you will need some more dependencies.
 ```bash
 $ sudo apt-get install libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev
@@ -43,7 +31,36 @@ Different distributions have different package installation mechanisms and somet
 
 Additional dependencies exist if you you plan to perform Frontend Development, please read the [Frontend](https://home-assistant.io/developers/frontend/) section to learn more.
 
-#### {% linkable_title Setting up virtual environment (optional) %} 
+#### {% linkable_title Developing on Windows %}
+
+If you are using Windows as a development platform, make sure that you have the correct Microsoft Visual C++ build tools installed. Check the [Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. Validation using `tox` will fail if this is not done correctly.
+
+Also, make sure to install or upgrade the `setuptools` Python package. It contains compatibility improvements and adds automatic use of compilers:
+
+```bash
+$ pip install --upgrade setuptools
+```
+
+#### {% linkable_title Developing on OS X %}
+
+Install [Homebrew](https://brew.sh/), then use that to install Python 3:
+
+```bash
+$ brew install python3
+```
+
+### {% linkable_title Setup Local Repository %}
+
+Visit the [Home Assistant repository](https://github.com/home-assistant/home-assistant) and click **Fork**.
+Once forked, setup your local copy of the source using the commands:
+
+```bash
+$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
+$ cd home-assistant
+$ git remote add upstream https://github.com/home-assistant/home-assistant.git
+```
+
+### {% linkable_title Setting up virtual environment (optional) %} 
 
 If you plan on providing isolation to your environment using [`venv`](https://docs.python.org/3.4/library/venv.html). Within the `home-assistant` directory, create and activate your virtual environment.
 
@@ -52,19 +69,13 @@ $ python3 -m venv venv
 $ source venv/bin/activate
 ```
 
-Note, Debian does not ship a full Python3 package and so requires you to install `venv` manually `sudo apt-get install python3-venv`.
-
 ### {% linkable_title Setup and Run %}
 
-* On Mac OS X and Linux:
-
 ```bash
 $ cd home-assistant
 $ script/setup
 ```
 
-* On Windows, you can use `python setup.py develop` instead of the setup script.
-
 * Run `hass` to invoke your local installation.
 
 ### {% linkable_title Logging %}
@@ -75,13 +86,3 @@ verbose logging levels).
 
 You can use the [logger](/components/logger/) component to adjust
 logging to DEBUG to see even more details about what is going on.
-
-### {% linkable_title Developing on Windows %}
-
-If you are using Windows as a development platform, make sure that you have the correct Microsoft Visual C++ build tools installed. Check the [Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. Validation using `tox` will fail if this is not done correctly.
-
-Also, make sure to install or upgrade the `setuptools` Python package. It contains compatibility improvements and adds automatic use of compilers:
-
-```bash
-$ pip install --upgrade setuptools
-```