diff --git a/README.md b/README.md
index 878652b41..e20f51b14 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,52 @@
-This is the Let's Encrypt Agent DEVELOPER PREVIEW repository.
+# Let's Encrypt
 
-DO NOT RUN THIS CODE ON A PRODUCTION WEBSERVER.  IT WILL INSTALL CERTIFICATES
-SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR USERS.
+## Disclaimer
 
-This code is intended for testing, demonstration, and integration engineering
-with OSes and hosting platforms.  Currently the code works with Linux and
-Apache, though we will be expanding it to other platforms.
+This is the [Let's Encrypt] Agent **DEVELOPER PREVIEW** repository.
 
-## Running the demo code on Ubuntu
+**DO NOT RUN THIS CODE ON A PRODUCTION WEBSERVER. IT WILL INSTALL
+CERTIFICATES SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR
+USERS.**
+
+This code is intended for testing, demonstration, and integration
+engineering with OSes and hosting platforms. For the time being
+project focuses on Linux and Apache, though we will be expanding
+it to other platforms.
+
+## Running the demo code
+
+The demo code is supported and known to work on **Ubuntu only** (even
+closely related [Debian is known to fail]
+(https://github.com/letsencrypt/lets-encrypt-preview/issues/68)).
+Therefore, prerequisites for other platforms listed below are provided
+mainly for the [developers](#hacking) reference.
+
+### Prerequisites
+
+In general:
+
+* [swig] is required for compiling [m2crypto]
+* [augeas] is required for the `python-augeas` bindings
+
+#### Ubuntu
 
 ```
 sudo apt-get install python python-setuptools python-virtualenv \
   python-dev gcc swig dialog libaugeas0 libssl-dev
+```
+
+#### Mac OSX
+
+`sudo brew install augeas swig`
+
+### Installation
+
+```
 virtualenv --no-site-packages venv
 ./venv/bin/python setup.py install
 sudo ./venv/bin/letsencrypt
 ```
 
-Note, that letsencrypt does not yet handle Debian unstable's Apache2
-conf layout.
-
 ## Hacking
 
 1. Bootstrap: `./venv/bin/python setup.py dev`
@@ -63,14 +90,20 @@ optional arguments:
 
 ## More Information
 
-Further Setup, documentation and open projects are available in the [Wiki]
-(https://github.com/letsencrypt/lets-encrypt-preview/wiki)
+- Further setup, documentation and open projects are available in the
+  [Wiki].
 
-Join us at our IRC channel @ freenode.net #letsencrypt
+- Join us at our IRC channel: #letsencrypt at [Freenode].
 
-Client software development can be discussed on this [mailing list]
-(https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev)
+- Client software development can be discussed on this [mailing
+  list]. To subscribe without a Google account, send an email to
+  client-dev+subscribe@letsencrypt.org.
 
-To subscribe without a Google account, send mail to
-[client-dev+subscribe@letsencrypt.org]
-(mailto:client-dev+subscribe@letsencrypt.org).
+
+[augeas]: http://augeas.net
+[Freenode]: https://freenode.net
+[Let's Encrypt]: https://letsencrypt.org
+[m2crypto]: https://github.com/M2Crypto/M2Crypto
+[mailing list]: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev
+[swig]: http://www.swig.org
+[wiki]: https://github.com/letsencrypt/lets-encrypt-preview/wiki