Merge pull request #2744 from k88hudson/docs

Add table of contents, clarification for docs

docs/v2-system-addon/1.GETTING_STARTED.md

@@ -1,5 +1,12 @@
 # Activity Stream (System add-on)
 
+## Contents of this guide
+
+- Installation, set-up, and other basics (this page)
+- [Writing unit tests](./unit_testing_guide.md)
+- [Adding new Telemetry (user and performance metrics)](./telemetry.md)
+- [Reading/changing Firefox prefs](./preferences.md)
+
 ## Where to ask questions
 
 - Most of the core dev team can be found on the `#activity-stream` mozilla irc channel.
@@ -8,27 +15,45 @@
 - Our Mozilla slack channel is #activitystream
 - File issues/questions on Github: https://github.com/mozilla/activity-stream/issues. We typically triage new issues every Monday.
 
-## Testing in Firefox Nightly
+## How to try Activity Stream
 
-If you just want to see the current version of Activity Stream in Firefox, you can
+If you just want to try out the current version of Activity Stream in Firefox, you can
 install [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly)
 go to `about:config`, and set the `browser.newtabpage.activity-stream.enabled` pref
 to `true`.
 
+## Source code and submitting pull requests
+
+Inside this repository, there are two versions of Activity Stream; the **test pilot version** (v1)
+and the **system add-on version** (v2).
+
+These docs refer to the **system add-on version**, which is the production version
+of Activity Stream that is included with Firefox. The latest copy of the source code
+for this version can be found in the [system-addon/](../../system-addon/) subdirectory.
+You can ignore the other directories/files in the repository.
+
+A copy of this code is exported to Mozilla central on a regular basis, which can
+be found at [browser/extensions/activity-stream](https://searchfox.org/mozilla-central/source/browser/extensions/activity-stream).
+Keep in mind that some of these files are generated, so if you intend on editing any files, you should
+do so in the Github version.
+
+Pull requests should be sent against the master branch of https://github.com/mozilla/activity-stream,
+NOT against Mozilla central.
+
 ## Prerequisites for development
 
-### Operating system
+### Operating system and software
 
 The Activity Stream development environment is designed to work on Mac and Linux.
 If you need to develop on Windows, you might want to reach out on IRC (#activity-stream)
 if you run into any problems.
 
-### Software
+You will also need to install:
 
-- Node.js 6.9.1+ (On Mac, the best way to install Node.js is to use the [install link on the Node.js homepage](https://nodejs.org/en/))
+- Node.js 7+ (On Mac, the best way to install Node.js is to use the [install link on the Node.js homepage](https://nodejs.org/en/))
 - npm (packaged with Node.js)
 
-### activity-stream
+### Activity Stream Github repository
 
 You will need to to clone Activity Stream to a local directory from the `master`
 branch of our Github repository: https://github.com/mozilla/activity-stream
@@ -51,19 +76,6 @@ Check out [these docs on artifact builds](https://developer.mozilla.org/en-US/do
 for instructions about how to download and configure Mozilla Central if you have
 never done so before.
 
-## Source code and PRs
-
-The latest copy of the source code for Activity Stream can be found in the `system-addon/`
-subdirectory of `activity-stream`.
-
-The current version of Activity Stream that is shipped with Firefox nightly can
-be found in `mozilla-central/browser/extensions/activity-stream`. Keep in mind that
-some of these files are generated, so if you intend on editing any files, you should
-do so in the Github version.
-
-PRs should be sent against the master branch of https://github.com/mozilla/activity-stream,
-NOT against mozilla central.
-
 ## Building
 
 1. Install required dependencies by running `npm install`.

system-addon/README.md

@@ -7,4 +7,4 @@ via the browser.newtabpage.activity-stream.enabled pref.
 The files in this directory, including vendor dependencies, are imported from the
 system-addon directory in https://github.com/mozilla/activity-stream.
 
-Read [docs/v2-system-addon](https://github.com/mozilla/activity-stream/tree/master/docs/v2-system-addon) for more detail.
+Read [docs/v2-system-addon](https://github.com/mozilla/activity-stream/tree/master/docs/v2-system-addon/1.GETTING_STARTED.md) for more detail.