diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 4e206afa4..048cd2b10 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,15 +1,69 @@
+Prerequisites
+=============
+
+The demo code is supported and known to work on **Ubuntu only** (even
+closely related `Debian is known to fail`_).
+
+Therefore, prerequisites for other platforms listed below are provided
+mainly for the :ref:`developers <hacking>` reference.
+
+In general:
+
+* `swig`_ is required for compiling `m2crypto`_
+* `augeas`_ is required for the ``python-augeas`` bindings
+
+.. _Debian is known to fail: https://github.com/letsencrypt/lets-encrypt-preview/issues/68
+
+Ubuntu
+------
+
+::
+
+    sudo apt-get install python python-setuptools python-virtualenv python-dev \
+                 gcc swig dialog libaugeas0 libssl-dev libffi-dev \
+                 ca-certificates
+
+.. Please keep the above command in sync with .travis.yml (before_install)
+
+Mac OSX
+-------
+
+::
+
+    sudo brew install augeas swig
+
+
+Installation
+============
+
+::
+
+    virtualenv --no-site-packages -p python2 venv
+    ./venv/bin/python setup.py install
+    sudo ./venv/bin/letsencrypt
+
+
+Usage
+=====
+
+The letsencrypt commandline tool has a builtin help:
+
+::
+
+   ./venv/bin/letsencrypt --help
+
+
+.. _augeas: http://augeas.net/
+.. _m2crypto: https://github.com/M2Crypto/M2Crypto
+.. _swig: http://www.swig.org/
+
 .. _hacking:
 
 Hacking
 =======
 
 In order to start hacking, you will first have to create a development
-environment. Start by installing the required system packages:
-
-::
-    sudo apt-get install python-2.7 python-pip swig  
-
-Now you can install the development packages in your virtualenv:
+environment. Start by installing the development packages:
 
 ::
     ./venv/bin/python setup.py dev
@@ -29,6 +83,7 @@ The following tools are there to help you:
 
 
 .. _coding-style:
+.. _setup instructions: https://letsencrypt.readthedocs.org/en/latest/using.html
 
 Coding style
 ============