diff --git a/README.mkd b/README.mkd
index d0d1f09b9..ccc09138b 100644
--- a/README.mkd
+++ b/README.mkd
@@ -13,6 +13,9 @@ mitmproxy.org website:
 [mitmproxy.org](http://mitmproxy.org).
 
 
+You can find complete directions for installing mitmproxy [here](http://mitmproxy.org/doc/install.html). 
+
+
 Features
 --------
 
@@ -26,19 +29,17 @@ Features
 - SSL certificates for interception are generated on the fly.
 - And much, much more.
 
-
-Installation
-------------
-
-The recommended way to install mitmproxy is running 
-
-`pip install mitmproxy`
-
-For convenience, we provide binary packages on [mitmproxy.org](http://mitmproxy.org/).
+__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. On Windows,
+only mitmdump is supported, which does not have a graphical user interface.
 
 
-Requirements
-------------
+
+Hacking
+-------
+
+
+### Requirements
+
 
 * [Python](http://www.python.org) 2.7.x.
 * [netlib](http://pypi.python.org/pypi/netlib), version matching mitmproxy.
@@ -52,19 +53,9 @@ Optional packages for extended content decoding:
 
 For convenience, all optional dependencies can be installed with 
 
-`pip install mitmproxy contentviews`
+`pip install "mitmproxy[contentviews]"`
 
-__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. On Windows,
-only mitmdump is supported, which does not have a graphical user interface.
-
-
-Hacking
--------
-
-The following components are needed if you plan to hack on mitmproxy:
-
-* The test suite requires the `dev` extra requirements listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py) and [pathod](http://pathod.net), version matching mitmproxy. Install these with `pip install mitmproxy dev`.
-* Rendering the documentation requires [countershape](http://github.com/cortesi/countershape).
+### Setting up a dev environment
 
 The following procedure is recommended to set up your dev environment:
 
@@ -76,6 +67,26 @@ $ pip install --src . -r requirements.txt
 
 This installs the latest GitHub versions of mitmproxy, netlib and pathod into `mitmproxy/`. All other development dependencies save countershape are installed into their usual locations. 
 
+
+### Testing
+
+The test suite requires the `dev` extra requirements listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py) and [pathod](http://pathod.net), version matching mitmproxy. Install these with:
+
+`
+pip install "mitmproxy[dev]""`
+
+
 Please ensure that all patches are accompanied by matching changes in the test
 suite. The project maintains 100% test coverage.
 
+
+### Docs
+
+Rendering the documentation requires [countershape](http://github.com/cortesi/countershape). After installation, you can render the documentation to the doc like this:
+
+`cshape doc-src doc`
+
+
+
+
+
diff --git a/doc-src/install.html b/doc-src/install.html
index 5f1e54fd1..8a76e3ae9 100644
--- a/doc-src/install.html
+++ b/doc-src/install.html
@@ -1,4 +1,8 @@
 
+
+
+## Installing from source
+
 The preferred way to install mitmproxy - whether you're installing the latest
 release or from source - is to use [pip](http://www.pip-installer.org/). If you
 don't already have pip on your system, you can find installation instructions
@@ -8,14 +12,24 @@ don't already have pip on your system, you can find installation instructions
 pip install mitmproxy
 </pre>
 
+If you also want to install the optional packages AMF, protobuf and CSS
+content views, do this:
+
+<pre class="terminal">
+pip install "mitmproxy[contentviews]"
+</pre>
+
 
 ## OSX
 
+The easiest way to get up and running on OSX is to download the pre-built
+binary packages from [mitmproxy.org](http://mitmproxy.org). If you still want
+to install using pip, there are a few things to keep in mind:
+
 - If you're running a Python interpreter installed with homebrew (or similar),
 you may have to install some dependencies by hand. 
 - Make sure that XCode is installed from the App Store, and that the
 command-line tools have been downloaded (XCode/Preferences/Downloads).
-- Now use __pip__ to do the installation, as above.
 
 There are a few bits of customization you might want to do to make mitmproxy
 comfortable to use on OSX. The default color scheme is optimized for a dark