diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..d7549f85f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing to Citus
+
+We're happy you want to contribute! You can help us in different ways:
+
+* Open an [issue](https://github.com/citusdata/citus/issues) with
+  suggestions for improvements
+* Fork this repository and submit a pull request
+
+### Getting and building
+
+#### Mac
+
+1. Install XCode
+2. Install packages with homebrew
+
+   ```bash
+   brew update
+   brew install git openssl postgresql
+   brew link openssl --force
+   ```
+
+3. Get the code
+
+   ```bash
+   git clone https://github.com/citusdata/citus.git
+   ```
+
+4. Build and test
+
+   ```bash
+   cd citus
+   ./configure
+   make
+   sudo make install
+   cd src/test/regress
+   make check-multi
+
+   # if you enncounter an error about __cg_jpeg_resync_to_restart, try
+   # brew uninstall libpng
+   # and retry make check-multi
+   ```
diff --git a/README.md b/README.md
index 810334bcc..e46441822 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 ![Citus Banner](/github-banner.png)
 
 [![Build Status](https://travis-ci.com/citusdata/citus.svg?token=bSq3ym67qubHCGNs1iYZ&branch=master)](https://travis-ci.com/citusdata/citus)
-[![Citus IRC](https://img.shields.io/badge/irc-%23citus-blue.svg)](irc://irc.freenode.net/citus)
-[![Latest Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://www.citusdata.com/documentation/citus-documentation-5/index.html)
+[![Citus IRC](https://img.shields.io/badge/irc-%23citus-blue.svg)](https://webchat.freenode.net/?channels=citus)
+[![Latest Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)][docs]
 
 ### What is Citus?
 
@@ -21,6 +21,8 @@ gives developers and enterprises the power and familiarity of a
 traditional relational database. As an extension, Citus supports
 new PostgreSQL releases, allowing users to benefit from new features
 while maintaining compatibility with existing PostgreSQL tools.
+Note that Citus supports many (but not all) SQL commands; see the
+[FAQ][faq] for more details.
 
 Common Use-Cases:
 * Powering real-time analytic dashboards
@@ -34,7 +36,7 @@ To learn more, visit [citusdata.com](https://www.citusdata.com).
 
 #### Local Citus Cluster
 
-* Install docker-compose: [Mac](https://www.docker.com/products/docker-toolbox) | [Linux](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-14-04)
+* Install docker-compose: [Mac][mac_install] | [Linux][linux_install]
 * (Mac only) connect to Docker VM
    ```bash
    eval $(docker-machine env default)
@@ -51,7 +53,7 @@ To learn more, visit [citusdata.com](https://www.citusdata.com).
    docker exec -it citus_master psql -U postgres -d postgres
    ```
 
-* Follow the [first tutorial](https://www.citusdata.com/documentation/citus-documentation-5/tutorials/tut-real-time.html) instructions
+* Follow the [first tutorial][tutorial] instructions
 * To shut the cluster down, run
 
    ```bash
@@ -60,23 +62,58 @@ To learn more, visit [citusdata.com](https://www.citusdata.com).
 
 ### Learn More
 
-The project [documentation](https://www.citusdata.com/documentation/citus-documentation-5/index.html) and
-[tutorials](https://www.citusdata.com/documentation/citus-documentation-5/tutorials/tut-real-time.html) are good places to start.
-We’re responsive on Github, so you can use the [issue
-tracker](https://github.com/citusdata/citus/issues) to check for or
-submit bug reports and feature requests. For more immediate help
-or general discussion we’re on IRC at `#citus` on Freenode and
-[@citusdata](https://twitter.com/citusdata) on Twitter.
+The project [documentation][docs] and [tutorials][tutorial] are
+good places to start.  We’re responsive on Github, so you can use
+the [issue tracker][issues]  to check for or submit bug reports and
+feature requests. For more immediate help or general discussion
+we’re on IRC at `#citus` on Freenode and [@citusdata][twitter] on
+Twitter.
 
 We also offer training and dedicated support options. More information
-is available on our [support
-page](https://www.citusdata.com/citus-products/citus-data-pricing).
+is available on our [support page][support].
 
 ### Contributing
 
 Citus is built on and of open source. We welcome your contributions,
 and have added a
 [helpwanted](https://github.com/citusdata/citus/labels/helpwanted) label
-to issues which are accessible to new contributors. The CONTRIBUTING.md
-file explains how to get started developing the Citus extension
-itself and our code quality guidelines.
+to issues which are accessible to new contributors. The
+[CONTRIBUTING.md](CONTRIBUTING.md) file explains how to get started
+developing the Citus extension itself and our code quality guidelines.
+
+### Who is Using Citus?
+
+Citus is deployed in production by many customers, ranging from
+technology start-ups to large enterprises. Here are some examples:
+
+* [CloudFlare](https://www.cloudflare.com/) uses Citus to provide
+real-time analytics on 100 TBs of data from over 4 million customer
+websites. [Case
+Study](https://blog.cloudflare.com/scaling-out-postgresql-for-cloudflare-analytics-using-citusdb/)
+* [MixRank](https://mixrank.com/) uses Citus to efficiently collect
+and analyze vast amounts of data to allow inside B2B sales teams
+to find new customers. [Case
+Study](https://www.citusdata.com/solutions/case-studies/mixrank-case-study)
+* [Neustar](https://www.neustar.biz/) builds and maintains scalable
+ad-tech infrastructure that counts billions of events per day using
+Citus and HyperLogLog.
+* [Agari](https://www.agari.com/) uses Citus to secure more than
+85 percent of U.S. consumer emails on two 6-8 TB clusters. [Case
+Study](https://www.citusdata.com/solutions/case-studies/agari-case-study)
+* [Heap](https://heapanalytics.com/) uses Citus to run dynamic
+funnel, segmentation, and cohort queries across billions of users
+and tens of billions of events. [Watch
+Video](https://www.youtube.com/watch?v=NVl9_6J1G60&list=PLixnExCn6lRpP10ZlpJwx6AuU3XIgNWpL)
+
+[docs]: https://www.citusdata.com/docs/citus/5.0
+[faq]: https://www.citusdata.com/frequently-asked-questions
+[issues]: https://github.com/citusdata/citus/issues
+[linux_install]: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-14-04
+[mac_install]: https://www.docker.com/products/docker-toolbox
+[support]: https://www.citusdata.com/citus-products/citus-data-pricing
+[tutorial]: https://www.citusdata.com/docs/citus/5.0/tutorials/tut-real-time.html
+[twitter]: https://twitter.com/citusdata
+
+___
+
+Copyright 2012-2016 Citus Data