diff --git a/README.md b/README.md
index 289b93534..d609aafd2 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ To learn how to contribute to the MetaMask project itself, visit our [Internal D
 - Install dependencies: `yarn setup` (not the usual install command)
 - Copy the `.metamaskrc.dist` file to `.metamaskrc`
     - Replace the `INFURA_PROJECT_ID` value with your own personal [Infura Project ID](https://infura.io/docs).
-    - If debugging MetaMetrics, you'll need to add a value for `SEGMENT_WRITE_KEY` [Segment write key](https://segment.com/docs/connections/find-writekey/).
+    - If debugging MetaMetrics, you'll need to add a value for `SEGMENT_WRITE_KEY` [Segment write key](https://segment.com/docs/connections/find-writekey/), see [Developing on MetaMask](./development/README.md).
 - Build the project to the `./dist/` folder with `yarn dist`.
 
 Uncompressed builds can be found in `/dist`, compressed builds can be found in `/builds` once they're built.
@@ -97,6 +97,7 @@ Whenever you change dependencies (adding, removing, or updating, either in `pack
 - [How to add a new translation to MetaMask](./docs/translating-guide.md)
 - [Publishing Guide](./docs/publishing.md)
 - [How to use the TREZOR emulator](./docs/trezor-emulator.md)
+- [Developing on MetaMask](./development/README.md) 
 - [How to generate a visualization of this repository's development](./development/gource-viz.sh)
 
 [1]: http://www.nomnoml.com/#view/%5B%3Cactor%3Euser%5D%0A%0A%5Bmetamask-ui%7C%0A%20%20%20%5Btools%7C%0A%20%20%20%20%20react%0A%20%20%20%20%20redux%0A%20%20%20%20%20thunk%0A%20%20%20%20%20ethUtils%0A%20%20%20%20%20jazzicon%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20account-detail%0A%20%20%20%20%20accounts%0A%20%20%20%20%20locked-screen%0A%20%20%20%20%20restore-vault%0A%20%20%20%20%20identicon%0A%20%20%20%20%20config%0A%20%20%20%20%20info%0A%20%20%20%5D%0A%20%20%20%5Breducers%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20metamask%0A%20%20%20%20%20identities%0A%20%20%20%5D%0A%20%20%20%5Bactions%7C%0A%20%20%20%20%20%5BbackgroundConnection%5D%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%5D%3A-%3E%5Bactions%5D%0A%20%20%20%5Bactions%5D%3A-%3E%5Breducers%5D%0A%20%20%20%5Breducers%5D%3A-%3E%5Bcomponents%5D%0A%5D%0A%0A%5Bweb%20dapp%7C%0A%20%20%5Bui%20code%5D%0A%20%20%5Bweb3%5D%0A%20%20%5Bmetamask-inpage%5D%0A%20%20%0A%20%20%5B%3Cactor%3Eui%20developer%5D%0A%20%20%5Bui%20developer%5D-%3E%5Bui%20code%5D%0A%20%20%5Bui%20code%5D%3C-%3E%5Bweb3%5D%0A%20%20%5Bweb3%5D%3C-%3E%5Bmetamask-inpage%5D%0A%5D%0A%0A%5Bmetamask-background%7C%0A%20%20%5Bprovider-engine%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bid%20store%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%3E%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%3C-%3E%5Bid%20store%5D%0A%20%20%5Bconfig%20manager%7C%0A%20%20%20%20%5Brpc%20configuration%5D%0A%20%20%20%20%5Bencrypted%20keys%5D%0A%20%20%20%20%5Bwallet%20nicknames%5D%0A%20%20%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%5Bconfig%20manager%5D%0A%20%20%5Bid%20store%5D%3C-%3E%5Bconfig%20manager%5D%0A%5D%0A%0A%5Buser%5D%3C-%3E%5Bmetamask-ui%5D%0A%0A%5Buser%5D%3C%3A--%3A%3E%5Bweb%20dapp%5D%0A%0A%5Bmetamask-contentscript%7C%0A%20%20%5Bplugin%20restart%20detector%5D%0A%20%20%5Brpc%20passthrough%5D%0A%5D%0A%0A%5Brpc%20%7C%0A%20%20%5Bethereum%20blockchain%20%7C%0A%20%20%20%20%5Bcontracts%5D%0A%20%20%20%20%5Baccounts%5D%0A%20%20%5D%0A%5D%0A%0A%5Bweb%20dapp%5D%3C%3A--%3A%3E%5Bmetamask-contentscript%5D%0A%5Bmetamask-contentscript%5D%3C-%3E%5Bmetamask-background%5D%0A%5Bmetamask-background%5D%3C-%3E%5Bmetamask-ui%5D%0A%5Bmetamask-background%5D%3C-%3E%5Brpc%5D%0A
diff --git a/development/README.md b/development/README.md
index a8e4eb6fc..16df8fb89 100644
--- a/development/README.md
+++ b/development/README.md
@@ -3,3 +3,54 @@
 Several files which are needed for developing on MetaMask.
 
 Usually each file or directory contains information about its scope / usage.
+
+## Segment
+
+### Debugging with the Mock Segment API
+
+To start the [Mock Segment API](./mock-segment.js):
+
+-   Add/replace the `SEGMENT_HOST` and `SEGMENT_WRITE_KEY` variables in `.metamaskrc`
+    ```
+    SEGMENT_HOST='http://localhost:9090'
+    SEGMENT_WRITE_KEY='FAKE'
+    ```
+-   Build the project to the `./dist/` folder with `yarn dist`
+-   Run the Mock Segment API from the command line
+    ```
+    node development/mock-segment.js
+    ```
+
+Events triggered whilst using the extension will be logged to the console of the Mock Segment API.
+
+More information on the API and its usage can be found [here](./mock-segment.js#L28).
+
+### Debugging in Segment
+
+To debug in a production Segment environment:
+
+- Create a free account on [Segment](https://segment.com/)
+- Create a New Workspace
+- Add a Source (Node.js)
+- Copy the `Write Key` from the API Keys section under Settings
+-   Add/replace the `SEGMENT_HOST` and `SEGMENT_WRITE_KEY` variables in `.metamaskrc`
+    ```
+    SEGMENT_HOST='https://api.segment.io'
+    SEGMENT_WRITE_KEY='COPIED_WRITE_KEY'
+    ```
+-   Build the project to the `./dist/` folder with `yarn dist`
+
+Events triggered whilst using the extension will be displayed in Segment's Debugger.
+
+### Debugging Segment requests in MetaMask
+
+To opt in to MetaMetrics;
+- Unlock the extension
+- Open the Account menu 
+- Click the `Settings` menu item
+- Click the `Security & Privacy` menu item
+- Toggle the `Participate in MetaMetrics` menu option to the `ON` position
+
+You can inspect the requests in the `Network` tab of your browser's Developer Tools (background.html)
+by filtering for `POST` requests to `/v1/batch`. The full url will be `http://localhost:9090/v1/batch`
+or `https://api.segment.io/v1/batch` respectively.
diff --git a/docs/README.md b/docs/README.md
index 6c54c98cf..4e87d90c1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,8 +13,5 @@ To learn how to develop MetaMask-compatible applications, visit our [Developer D
 - [How to add custom build to Chrome](./add-to-chrome.md)
 - [How to add custom build to Firefox](./add-to-firefox.md)
 - [Publishing Guide](./publishing.md)
-- [How to live reload on local dependency changes](./developing-on-deps.md)
-- [How to add new networks to the Provider Menu](./adding-new-networks.md)
-- [How to port MetaMask to a new platform](./porting_to_new_environment.md)
-- [How to generate a visualization of this repository's development](./development-visualization.md)
 - [How to add a feature behind a secret feature flag](./secret-preferences.md)
+- [Developing on MetaMask](../development/README.md)