Merge pull request #505 from 0xProject/fix/readmeContributingSection

Improve README contributing sections in all packages

22 files changed, 664 insertions, 64 deletions

diff --git a/packages/0x.js/README.md b/packages/0x.js/README.md
index 5b17dac8b..46848cbdd 100644
--- a/packages/0x.js/README.md
+++ b/packages/0x.js/README.md
@@ -1,5 +1,9 @@
 ## 0x.js
 
+A TypeScript/Javascript library for interacting with the 0x protocol.
+
+### Read the [Documentation](0xproject.com/docs/0xjs).
+
 ## Installation
 
 0x.js ships as both a [UMD](https://github.com/umdjs/umd) module and a [CommonJS](https://en.wikipedia.org/wiki/CommonJS) package.
@@ -38,10 +42,66 @@ Download the UMD module from our [releases page](https://github.com/0xProject/0x
 <script type="text/javascript" src="0x.js"></script>
 ```
 
-## Documentation
+## Contributing
+
+We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+
+Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
+
+### Install dependencies
+
+If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
+
+```bash
+yarn config set workspaces-experimental true
+```
+
+Then install dependencies
+
+```bash
+yarn install
+```
+
+### Build
+
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
+```bash
+yarn build
+```
+
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
+### Lint
 
-Extensive documentation of 0x.js can be found on [our website][docs-url].
+```bash
+yarn lint
+```
+
+### Run Tests
 
-[website-url]: https://0xproject.com/
-[whitepaper-url]: https://0xproject.com/pdfs/0x_white_paper.pdf
-[docs-url]: https://0xproject.com/docs/0xjs
+```bash
+yarn test
+```
diff --git a/packages/abi-gen/README.md b/packages/abi-gen/README.md
index 899b4845e..301bd709f 100644
--- a/packages/abi-gen/README.md
+++ b/packages/abi-gen/README.md
@@ -57,3 +57,61 @@ See the [type definition](https://github.com/0xProject/0x-monorepo/tree/developm
 ## Output files
 
 Output files will be generated within an output folder with names converted to camel case and taken from abi file names. If you already have some files in that folder they will be overwritten.
+
+## Contributing
+
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
+
+Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
+
+### Install dependencies
+
+If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
+
+```bash
+yarn config set workspaces-experimental true
+```
+
+Then install dependencies
+
+```bash
+yarn install
+```
+
+### Build
+
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
+```bash
+yarn build
+```
+
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
+### Lint
+
+```bash
+yarn lint
+```
diff --git a/packages/assert/README.md b/packages/assert/README.md
index 7f80e7e5d..598fee613 100644
--- a/packages/assert/README.md
+++ b/packages/assert/README.md
@@ -26,11 +26,11 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
 
 ## Contributing
 
-We strongly encourage that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -46,10 +46,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/connect/README.md b/packages/connect/README.md
index 7087214d6..a57fefa59 100644
--- a/packages/connect/README.md
+++ b/packages/connect/README.md
@@ -23,11 +23,11 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
 
 ## Contributing
 
-We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -43,10 +43,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/contracts/README.md b/packages/contracts/README.md
index 7628b057b..286ef019c 100644
--- a/packages/contracts/README.md
+++ b/packages/contracts/README.md
@@ -34,11 +34,25 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
diff --git a/packages/deployer/README.md b/packages/deployer/README.md
index 812e8c31b..d8b049bdf 100644
--- a/packages/deployer/README.md
+++ b/packages/deployer/README.md
@@ -41,11 +41,11 @@ var Compiler = require('@0xproject/deployer').Compiler;
 
 ## Contributing
 
-We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -61,16 +61,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
 ```
 
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/dev-utils/README.md b/packages/dev-utils/README.md
index d7e580d9f..2b183f1c7 100644
--- a/packages/dev-utils/README.md
+++ b/packages/dev-utils/README.md
@@ -26,3 +26,67 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
     "typeRoots": ["node_modules/@0xproject/typescript-typings/types", "node_modules/@types"],
 }
 ```
+
+## Contributing
+
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
+
+Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
+
+### Install dependencies
+
+If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
+
+```bash
+yarn config set workspaces-experimental true
+```
+
+Then install dependencies
+
+```bash
+yarn install
+```
+
+### Build
+
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
+```bash
+yarn build
+```
+
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
+### Lint
+
+```bash
+yarn lint
+```
+
+### Run Tests
+
+```bash
+yarn test
+```
diff --git a/packages/json-schemas/README.md b/packages/json-schemas/README.md
index 980d17416..e8cece63b 100644
--- a/packages/json-schemas/README.md
+++ b/packages/json-schemas/README.md
@@ -32,11 +32,11 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
 
 ## Contributing
 
-We strongly encourage that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -52,16 +52,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
 ```
 
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/monorepo-scripts/README.md b/packages/monorepo-scripts/README.md
index dbdfdf135..a740ba28a 100644
--- a/packages/monorepo-scripts/README.md
+++ b/packages/monorepo-scripts/README.md
@@ -16,11 +16,11 @@ This will list out any dependencies that differ in versions between packages.
 
 ## Contributing
 
-We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -36,11 +36,25 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
@@ -57,3 +71,9 @@ yarn clean
 ```bash
 yarn lint
 ```
+
+### Run Tests
+
+```bash
+yarn test
+```
diff --git a/packages/react-docs-example/README.md b/packages/react-docs-example/README.md
index 7b2547b20..ff821dba8 100644
--- a/packages/react-docs-example/README.md
+++ b/packages/react-docs-example/README.md
@@ -20,7 +20,19 @@ Then install dependencies
 yarn install
 ```
 
-#### Start the dev server
+### Initial setup
+
+The **first** time you work with this package, you must build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Note: If you move this package out of the monorepo, it will work without this step. Make sure you copy it out on the `master` branch since the `development` version might rely on not-yet published changes to other packages.
+
+### Run dev server
+
+The the `react-docs-example` root directory, run:
 
 ```bash
 yarn dev
@@ -42,6 +54,12 @@ yarn deploy_example
 yarn build
 ```
 
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/react-docs/README.md b/packages/react-docs/README.md
index 9be370f10..5a46b84f0 100644
--- a/packages/react-docs/README.md
+++ b/packages/react-docs/README.md
@@ -51,11 +51,11 @@ Feel free to contribute to these improvements!
 
 ## Contributing
 
-We strongly encourage the community to help us make improvements. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -71,10 +71,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/react-shared/README.md b/packages/react-shared/README.md
index 9165cf78d..0b4188180 100644
--- a/packages/react-shared/README.md
+++ b/packages/react-shared/README.md
@@ -18,11 +18,11 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
 
 ## Contributing
 
-We strongly encourage that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -38,18 +38,38 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-### Lint
+or continuously rebuild on change:
 
 ```bash
-yarn lint
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
 ```
 
-### Run Tests
+### Lint
 
 ```bash
-yarn test
+yarn lint
 ```
diff --git a/packages/sol-cov/README.md b/packages/sol-cov/README.md
index 5591b9731..8cc7dca6c 100644
--- a/packages/sol-cov/README.md
+++ b/packages/sol-cov/README.md
@@ -24,11 +24,11 @@ var CoverageSubprovider = require('@0xproject/sol-cov').CoverageSubprovider;
 
 ## Contributing
 
-We strongly encourage the community to help us make improvements. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -42,8 +42,46 @@ Then install dependencies
 yarn install
 ```
 
+### Build
+
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
+```bash
+yarn build
+```
+
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
 yarn lint
 ```
+
+### Run Tests
+
+```bash
+yarn test
+```
diff --git a/packages/sra-report/README.md b/packages/sra-report/README.md
index 299d575d8..806ac3bf4 100644
--- a/packages/sra-report/README.md
+++ b/packages/sra-report/README.md
@@ -87,11 +87,11 @@ In order to provide a custom environment to the tool, perform the following step
 
 ## Contributing
 
-We strongly encourage that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -107,10 +107,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/subproviders/README.md b/packages/subproviders/README.md
index ac92b89d2..2936be545 100644
--- a/packages/subproviders/README.md
+++ b/packages/subproviders/README.md
@@ -22,11 +22,11 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
 
 ## Contributing
 
-We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -34,17 +34,33 @@ If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 yarn config set workspaces-experimental true
 ```
 
+Then install dependencies
+
 ```bash
 yarn install
 ```
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
diff --git a/packages/testnet-faucets/README.md b/packages/testnet-faucets/README.md
index 2f6ae347f..93f97e1b7 100644
--- a/packages/testnet-faucets/README.md
+++ b/packages/testnet-faucets/README.md
@@ -4,15 +4,15 @@ This faucet dispenses 0.1 test ether to one recipient per second and 0.1 test ZR
 
 ## Installation
 
-This is a private package and therefore is not published to npm. In order to build and run this package locally, see the [Install Dependencies](#Install-Dependencies) section and onwards below.
+This is a private package and therefore is not published to npm. In order to build and run this package locally, see the contributing instructions below.
 
 ## Contributing
 
-We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -26,6 +26,44 @@ Then install dependencies
 yarn install
 ```
 
+### Build
+
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
+```bash
+yarn build
+```
+
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
+### Lint
+
+```bash
+yarn lint
+```
+
 ### Start
 
 Set the following environment variables:
@@ -125,9 +163,3 @@ docker run -d \
 -e INFURA_API_KEY=$INFURA_API_KEY \
 testnet-faucets
 ```
-
-### Lint
-
-```bash
-yarn lint
-```
diff --git a/packages/tslint-config/README.md b/packages/tslint-config/README.md
index b517f2d95..d90b3cf73 100644
--- a/packages/tslint-config/README.md
+++ b/packages/tslint-config/README.md
@@ -20,11 +20,11 @@ Add the following to your `tslint.json` file
 
 ## Contributing
 
-We strongly encourage that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -40,16 +40,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
 ```
 
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/types/README.md b/packages/types/README.md
index b971eaee7..665701ea4 100644
--- a/packages/types/README.md
+++ b/packages/types/README.md
@@ -24,13 +24,13 @@ import { TransactionReceipt, TxData, TxDataPayable } from '@0xproject/types';
 
 ## Contributing
 
-We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
-If you don't have yarn workspaces e`nabled (Yarn < v1.0) - enable them:
+If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
 ```bash
 yarn config set workspaces-experimental true
@@ -44,16 +44,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
 ```
 
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/typescript-typings/README.md b/packages/typescript-typings/README.md
index 9a74739f3..968b2e87c 100644
--- a/packages/typescript-typings/README.md
+++ b/packages/typescript-typings/README.md
@@ -20,11 +20,11 @@ This will allow the TS compiler to first look into that repo and then fallback t
 
 ## Contributing
 
-We strongly encourage that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -38,6 +38,38 @@ Then install dependencies
 yarn install
 ```
 
+### Build
+
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
+```bash
+yarn build
+```
+
+or continuously rebuild on change:
+
+```bash
+yarn build:watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/utils/README.md b/packages/utils/README.md
index fde0780a9..914404937 100644
--- a/packages/utils/README.md
+++ b/packages/utils/README.md
@@ -24,11 +24,11 @@ import { addressUtils, bigNumberConfigs, classUtils, intervalUtils, promisify }
 
 ## Contributing
 
-We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -44,16 +44,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
 ```
 
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/web3-wrapper/README.md b/packages/web3-wrapper/README.md
index e7491acb0..1ff85420a 100644
--- a/packages/web3-wrapper/README.md
+++ b/packages/web3-wrapper/README.md
@@ -20,11 +20,11 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
 
 ## Contributing
 
-We strongly encourage that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
 
 Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
 
-### Install Dependencies
+### Install dependencies
 
 If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
 
@@ -40,16 +40,36 @@ yarn install
 
 ### Build
 
+If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
+
+```bash
+yarn lerna:rebuild
+```
+
+Or continuously rebuild on change:
+
+```bash
+yarn dev
+```
+
+You can also build this specific package by running the following from within its directory:
+
 ```bash
 yarn build
 ```
 
-or
+or continuously rebuild on change:
 
 ```bash
 yarn build:watch
 ```
 
+### Clean
+
+```bash
+yarn clean
+```
+
 ### Lint
 
 ```bash
diff --git a/packages/website/README.md b/packages/website/README.md
index 042df52de..d93d18935 100644
--- a/packages/website/README.md
+++ b/packages/website/README.md
@@ -28,20 +28,24 @@ Add the following to your `/etc/hosts` file:
 yarn install
 ```
 
-### Run dev server
+### Initial setup
+
+The **first** time you work with this package, you must build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:
 
 ```bash
-yarn run dev
+yarn lerna:rebuild
 ```
 
-Visit [0xproject.localhost:3572](http://0xproject.localhost:3572) in your browser.
+### Run dev server
 
-### Build
+The the `website` root directory, run:
 
 ```bash
-yarn build
+yarn dev
 ```
 
+Visit [0xproject.localhost:3572](http://0xproject.localhost:3572) in your browser.
+
 ### Clean
 
 ```bash