Tweaking docs a bit to reflect recent changes

docs/aboutus/index.md

@@ -9,7 +9,7 @@ nav: aboutus
 
 # About Us
 
-We are a three member team that works on sitespeed.io in our free time. New contributors and team members are very welcomed!
+We are a three member team that works on sitespeed.io in our free time. New contributors and team members are very much welcome!
 
 ## Jonathan Lee
 <a href="https://twitter.com/beenanner"><img src="{{site.baseurl}}/img/aboutus/jonathan.jpg" class="photo pull-left" width="200" height="200"></a> I discovered sitespeed.io version 3 in 2015 while exploring the latest trending tools in web performance.  I was intrigued by this tool and decided to learn more. Wanting to contribute back to the open source community that has giving me so much over the last decade, I reached out to Peter and Tobias to assist with the development of version 4.0.  

docs/documentation/sitespeed.io/browsers/index.md

@@ -26,7 +26,7 @@ Chrome should work out of the box.
 ## Change connectivity
 You can throttle the connection to make the connectivity slower to make it easier to catch regressions. The best way to do that is to setup a network bridge in Docker.
 
-Default we use [TSProxy](https://github.com/WPO-Foundation/tsproxy) because it's only dependency is Python 2.7 but we have a problem with that together with Selenium, so that it is kind of unusable right now. Help us fix that in [#229](https://github.com/sitespeedio/browsertime/issues/229).
+By default we expect an external tool to handled connectivity. In the past we used [TSProxy](https://github.com/WPO-Foundation/tsproxy) because it's only dependency was Python 2.7, but unfortunetly we have a problem with it and Selenium, so it was removed as the default due to it's instability. Help us fix that in [#229](https://github.com/sitespeedio/browsertime/issues/229).
 
 If you run Docker you can use tc as connectivity engine but that will only set the latency, if you want to set the download speed you need to create a network bridge in Docker.
 
@@ -56,16 +56,16 @@ tc class add dev docker4 parent 1:1 classid 1:12 htb rate 0.4mbit ceil 0.4mbit
 tc qdisc add dev docker4 parent 1:12 netem delay 400ms
 ~~~
 
-Then when you run your container you add the network with <code>--network cable</code>. You should also tell Browsertime that you set the connectivity external from BT. A full example running running with cable:
+When you run your container you add the network with <code>--network cable</code>. A full example running running with cable:
 
 ~~~bash
-$ docker run --privileged --shm-size=1g --network=cable --rm sitespeedio/sitespeed.io -c cable --browsertime.connectivity.engine external https://www.sitespeed.io/
+$ docker run --privileged --shm-size=1g --network=cable --rm sitespeedio/sitespeed.io -c cable https://www.sitespeed.io/
 ~~~
 
 And using the 3g network:
 
 ~~~bash
-$ docker run --privileged --shm-size=1g --network=3g --rm sitespeedio/sitespeed.io -c 3g --browsertime.connectivity.engine external https://www.sitespeed.io/
+$ docker run --privileged --shm-size=1g --network=3g --rm sitespeedio/sitespeed.io -c 3g https://www.sitespeed.io/
 ~~~
 
 And if you want to remove the networks:
@@ -80,24 +80,24 @@ docker network rm cable
 ~~~
 
 ## Choose when to end your test
-By default the browser will collect data until  [window.performance.timing.loadEventEnd happens + aprox 2 seconds more](https://github.com/sitespeedio/browsertime/blob/d68261e554470f7b9df28797502f5edac3ace2e3/lib/core/seleniumRunner.js#L15). That is perfectly fine for most sites, but if you do Ajax loading and you mark them with user timings, you probably want to include them in your test. Do that by changing the script that will end the test (--browsertime.pageCompleteCheck). When the scripts returns true the browser will close or if the timeout time will be reached.
+By default the browser will collect data until  [window.performance.timing.loadEventEnd happens + aprox 2 seconds more](https://github.com/sitespeedio/browsertime/blob/d68261e554470f7b9df28797502f5edac3ace2e3/lib/core/seleniumRunner.js#L15). That is perfectly fine for most sites, but if you do Ajax loading and you mark them with user timings, you probably want to include them in your test. Do that by changing the script that will end the test (--browsertime.pageCompleteCheck). When the scripts returns true the browser will close or if the timeout time is reached.
 
-In this we wait 10 seconds until loadEventEnd happens but you can also choose to trigger it at a specific event.
+In this example we wait 10 seconds until the loadEventEnd happens, but you can also choose to trigger it at a specific event.
 
 ~~~bash
 $ sitespeed.io https://www.sitespeed.io --browsertime.pageCompleteCheck 'return (function() {try { return (Date.now() - window.performance.timing.loadEventEnd) > 10000;} catch(e) {} return true;})()'
 ~~~
 
-We use Selenium in the backend to drive the browsers and right now Selenium/drivers doesn't support the *pageLoadStrategies* where you can change when Selenium will give control to the user. Right now we always wait on the pageLoadEvent, meaning pages that doesn't fire that event will fail. Track the progress to fix that [here](https://github.com/sitespeedio/browsertime/issues/186).
+We use Selenium in the backend to drive the browsers and right now Selenium/drivers doesn't support the *pageLoadStrategies* where you can change when Selenium will give control to the user. Right now we always wait on the pageLoadEvent, meaning pages that do not fire that event will fail. Track the progress to fix that [here](https://github.com/sitespeedio/browsertime/issues/186).
 {: .note .note-warning}
 
 ## Custom metrics
 
-You can collect your own metrics in the browser by supplying Javascript file(s). By default we collect all metrics inside [these folders](https://github.com/sitespeedio/browsertime/tree/master/browserscripts) but you might have something else you want to collect.
+You can collect your own metrics in the browser by supplying Javascript file(s). By default we collect all metrics inside [these folders](https://github.com/sitespeedio/browsertime/tree/master/browserscripts), but you might have something else you want to collect.
 
 Each javascript file need to return a metric/value which will be picked up and returned in the JSON. If you return a number, statistics will automatically be generated for the value (like median/percentiles etc).
 
-Say we have one file called scripts.js that checks how many scripts tags exist on a page. The script looks like this:
+For example say we have one file called scripts.js that checks how many scripts tags exist on a page. The script would look like this:
 
 ~~~bash
 (function() {
@@ -105,7 +105,7 @@ Say we have one file called scripts.js that checks how many scripts tags exist o
 })();
 ~~~
 
-Then to pick up the script, run like this:
+Then to pick up the script, you would run it like this:
 
 ~~~bash
 sitespeed.io https://www.sitespeed.io --browsertime.script scripts.js -b firefox
@@ -119,11 +119,11 @@ And in the summary and detailed summary section.
 ![Summary page]({{site.baseurl}}/img/summary.png)
 {: .img-thumbnail}
 
-One more thing: All custom scripts values will be sent to Graphite, no extra configuration needed!
+Bonus: All custom scripts values will be sent to Graphite, no extra configuration needed!
 
 ## Visual Metrics
 
-Visual metrics (Speed Index, Perceptual Speed Index, first and last visual change) can be collected if you also record a video of the screen. This will work on desktop for Firefox & Chrome. And use our Docker container so you automagically get all the extra software needed.
+Visual metrics (Speed Index, Perceptual Speed Index, first and last visual change) can be collected if you also record a video of the screen. This will work on desktop for Firefox & Chrome. If you use our Docker container you automagically get all the extra software needed!
 
 ~~~bash
 $ docker run --privileged --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io --speedIndex --video https://www.sitespeed.io/
@@ -134,4 +134,4 @@ Everything you can do in Browsertime, you can also do in sitespeed.io. Prefixing
 
 You can check what Browsertime can do [here](https://github.com/sitespeedio/browsertime/blob/master/lib/support/cli.js).
 
-For example you wanna pass on an extra Chrome arguments to Chrome. In standalone Browsertime you do that with <code>--chrome.args</code>. If you wanna do that through sitespeed.io you just prefix browsertime to the param: <code>--browsertime.chrome.args</code>. Yes we know, pretty sweet! :)
+For example if you want to pass on an extra native arguments to Chrome. In standalone Browsertime you do that with <code>--chrome.args</code>. If you want to do that through sitespeed.io you just prefix browsertime to the param: <code>--browsertime.chrome.args</code>. Yes we know, pretty sweet! :)

docs/documentation/sitespeed.io/configuration/index.md

@@ -214,7 +214,7 @@ http://www.yoursite.com/where/we/are/ Page2
 ~~~
 *Note: Spaces are used to delimit between the URL and the alias which is why the alias cannot contain one.*
 
-Aliases are great in combination with sending metrics to a TSDB such as graphite for shortening the key sent to make they more readable.
+Aliases are great in combination with sending metrics to a TSDB such as graphite for shortening the key sent to make them more user friendly and readable.
 
 And run it:
 
@@ -244,13 +244,9 @@ Choose which browser to use (default is Chrome):
 $ sitespeed.io https://www.sitespeed.io -b firefox
 ~~~
 
-~~~bash
-$ sitespeed.io https://www.sitespeed.io -b chrome
-~~~
-
 ### Connectivity
 
-You should throttle the connection when you are fetching metrics. The best way to do that is to add network to your Docker container:
+You should throttle the connection when you are fetching metrics. The best way to do that is to use Docker and  add a network to your Docker container:
 
 ~~~bash
 docker network create --driver bridge --subnet=192.168.34.0/24 --gateway=192.168.34.10 --opt "com.docker.network.bridge.name"="docker2" cable
@@ -290,7 +286,7 @@ Mobile testing is always best on an actual mobile devices. You can [test on Andr
 
 ### Connectivity
 
-You can fake the connectivity for the browser. By default we use [TSProxy](https://github.com/WPO-Foundation/tsproxy) so you need Python 2.7 to work but you can also set the connectivity engine to [tc](http://lartc.org/manpages/tc.txt) if that works better for you.
+You can fake the connectivity for the browser. By default we expect an external tool to handle the connectivity, but you can also set the connectivity engine to [tc](http://lartc.org/manpages/tc.txt) or [TSProxy](https://github.com/WPO-Foundation/tsproxy), but you need Python 2.7 for that to work work if either of those works better for you.
 
 Setting the connectivity to cable:
 
@@ -305,7 +301,7 @@ $ sitespeed.io -c cable --browsertime.connectivity.engine tc https://www.sitespe
 ~~~
 
 ### Speed Index and video
-In 4.1 we released support for recording a video of the browser screen and use that to calculate visual metrics like Speed Index. Use our Docker containers for a easy setup.
+In 4.1 we released support for recording a video of the browser screen and use that to calculate visual metrics like Speed Index. Thsi is one of the main benefits for using our Docker images as it make for an easy setup. Without Docker you would need to install all these [dependencies](https://github.com/WPO-Foundation/visualmetrics) first.
 
 If you only care about Speed Index and related metrics (first visual change etc) you can run like this:
 
@@ -376,12 +372,12 @@ If you wanna override and run the same configuration but using Firefox, you just
 $ sitespeed.io --config config.json -b firefox https://www.sitespeed.io
 ~~~
 
-CLI will always override your JSON config.
+The CLI will always override a JSON config.
 
 ## Advanced
 
 ### Slack
-You can send the result of a run to Slack. First setup a webhook in the slack API (https://<your team>.slack.com/apps/manage/custom-integrations) and then configure it:
+You can send the result of a run to Slack. First setup a webhook in the Slack API (https://<your team>.slack.com/apps/manage/custom-integrations) and then configure it:
 
 ~~~bash
 $ sitespeed.io https://www.sitespeed.io/ --slack.hookUrl https://hooks.slack.com/services/YOUR/HOOK/URL

docs/documentation/sitespeed.io/developers/index.md

@@ -17,10 +17,10 @@ twitterdescription: Hack on sitespeed.io
 {:toc}
 
 ## Start
-Start by looking at the image of [how it all works]({{site.baseurl}}/documentation/sitespeed.io/how-it-all-works/). It seems like much, but it isn't that complicated.
+Start by looking at the image of [how it all works]({{site.baseurl}}/documentation/sitespeed.io/how-it-all-works/). It may seems like a lot, but it isn't that complicated.
 
 ## Setup
-On your local you need:
+On your local machine you need:
 * [Install NodeJS](https://nodejs.org/en/download/) latest LTS version
 * Fork [sitespeed.io](https://github.com/sitespeedio/sitespeed.io) and clone the forked repository
 * Go to the cloned directory and run *npm install*
@@ -54,7 +54,7 @@ The flow looks like this:
 5. Finish
 
 ## Using Pug
-We use [Pug](https://pugjs.org) as template for the HTML. If you are used to debug with console.log we have a special feature for you. We pass on JSON to the template, so if you want to output the data structure in the HTML you can do that by just adding:
+We use [Pug](https://pugjs.org) as template for the HTML. If you are use to debug with console.log we have a special feature for you. We pass on JSON to the template, so if you want to output the data structure in the HTML you can do that by just adding:
 
 ~~~
 p #{JSON.stringify(pageInfo)}
@@ -63,7 +63,7 @@ p #{JSON.stringify(pageInfo)}
 Where pageInfo is the data structure that you wanna inspect.
 
 ## Use sitespeed.io from NodeJS
-If you want to integrate sitespeed.io into your NodeJS application you can checkout how we do that in [our Grunt plugin](https://github.com/sitespeedio/grunt-sitespeedio/blob/master/tasks/sitespeedio.js). It is a working example :)
+If you want to integrate sitespeed.io into your NodeJS application you can checkout how we do that in [our Grunt plugin](https://github.com/sitespeedio/grunt-sitespeedio/blob/master/tasks/sitespeedio.js). It's a great working example. :)
 
 ## Contributing to the Documentation
 First make sure you have Bundler: <code>gem install bundler</code>

docs/documentation/sitespeed.io/getting-started/index.md

@@ -17,7 +17,7 @@ twitterdescription: Introduction for sitespeed.io.
 
 Sitespeed.io is an Open Source tool that helps you measuring the performance of your web site. You can [install](../installation/) it using [npm](https://www.npmjs.org/)/[yarn](https://yarnpkg.com/)/[Docker](https://www.docker.com/).
 
-Test your site against web performance best practice rules (using the [Coach]({{site.baseurl}}/documentation/coach/)), collect timing metrics from Chrome/Firefox (using [Browsertime]({{site.baseurl}}/documentation/browsertime/)) and get a report on how your site is performing. You can generate a HTML report (check out the [examples](/examples/) section to see what it looks like). You can use the Graphite plugin and build graphs with Grafana, checkout our example site [https://dashboard.sitespeed.io](https://dashboard.sitespeed.io). You can even build your own plugin that handles all the metrics that are collected.
+You can test your site against web performance best practice rules (using the [Coach]({{site.baseurl}}/documentation/coach/)) or collect timing metrics from Chrome/Firefox (using [Browsertime]({{site.baseurl}}/documentation/browsertime/)) and get a report on how your site is performing. You can generate a HTML report (check out the [examples](/examples/) section to see what it looks like). You can even use the Graphite plugin and build graphs with Grafana, checkout our example site [https://dashboard.sitespeed.io](https://dashboard.sitespeed.io). If that isn't enough you can build your own plugin that handles all the metrics that are collected in anyway you can imagine.
 
 In October 2016 we released 4.0 (sitespeed.io is 4 years old). One of the main goals with 4.0 was to make it easier for people to contribute and use. We have already have more contributions than ever before. With 3.X we got the following feedback in the [Toolsday](http://www.toolsday.io/) podcast:
 
@@ -26,10 +26,12 @@ SpeedCurve has a really low barrier of entry ... it's a bit of a evolution maybe
  <span>By Taylor Jones (IBM) on the podcast Toolsday http://www.toolsday.io/episodes/performance.html</span>
 </blockquote>
 
-Note: SpeedCurve is a paid service built on top on the Open Source tool  [WebPageTest](http://www.webpagetest.org/). If you love WebPageTest (we do!) you can [drive it](../webpagetest/) using sitespeed.io and collect the metrics and use it side by side with the sitespeed.io metrics.
+Note: SpeedCurve is a paid service built on top on the Open Source tool  [WebPageTest](http://www.webpagetest.org/). If you love WebPageTest (we do!) you can [drive it](../webpagetest/) using sitespeed.io and collect the metrics and use it side by side with all the sitespeed.io metrics.
 
 To get started you need either [NodeJS](https://nodejs.org/en/download/) ([Linux](https://github.com/creationix/nvm)) and  [npm](https://github.com/npm/npm)/[yarn](https://yarnpkg.com/)) or [Docker](https://docs.docker.com/engine/installation/).
 
 You also need [Firefox](https://www.mozilla.org/en-US/firefox/new/) and/or [Chrome](https://www.google.com/chrome/).
 
+We prefer and highly recommend Docker, since all the above requirements are handled for you plus more!
+
 If you've installed the prerequisites, head over to the [installation](../installation/) section and get going!

docs/documentation/sitespeed.io/how-it-all-works/index.md

@@ -15,7 +15,7 @@ twitterdescription: How it all works.
 * Lets place the TOC here
 {:toc}
 
-## What happens when sitespeed.io analyzes a page (10 seconds version)
+## What happens when sitespeed.io analyzes a page (the 10 step version)
 This is the super simple version, leaving out all other tools that are used:
 
 1. sitespeed.io gets a URL from the user
@@ -27,7 +27,7 @@ This is the super simple version, leaving out all other tools that are used:
 7. Stop the video and close the browser
 8. Analyze the video to get metrics like FirstVisualChange and SpeedIndex
 9. Generate a HTML report and/or send the metrics to Graphite or store the metrics however you want, building your own plugin.
-
+10. Enjoy!
 
 ## The big picture (with all the tools)
 The big picture looks something like this:
@@ -36,7 +36,7 @@ The big picture looks something like this:
 {: .img-thumbnail}
 
 ### Built upon Open Source
-Sitespeed.io uses a lot of other Open Source tools massive love to those projects:
+Sitespeed.io uses a lot of other Open Source tools so massive love to those projects and maintainers:
 
  * [Selenium](http://www.seleniumhq.org/)
  * [Visual Metrics](https://github.com/WPO-Foundation/visualmetrics)

docs/documentation/sitespeed.io/installation/index.md

@@ -17,39 +17,18 @@ twitterdescription: Install sitespeed.io using npm, yarn or Docker.
 
 # Install
 
-## Mac & Linux
-
-Prerequisites: Install [NodeJS 6.9.1 or newer](https://nodejs.org/en/download/) ([Linux](https://github.com/creationix/nvm)) and make sure you have [npm](https://github.com/npm/npm) or [yarn](https://yarnpkg.com/) installed. You can also use [Docker](https://docs.docker.com/engine/installation/) if you prefer.
-
-### npm
-If you prefer npm, just run:
-
-~~~ bash
-$ npm install sitespeed.io -g
-$ sitespeed.io --help
-~~~
-
-### yarn
-Or with [yarn](https://yarnpkg.com/):
-
-~~~ bash
-$ yarn global add sitespeed.io
-$ sitespeed.io --help
-~~~
-
-### Docker
+## Docker
 
 We have [Docker images](https://hub.docker.com/u/sitespeedio/) with sitespeed.io, Chrome, Firefox and Xvfb. They are super easy to use (Xvfb is started automatically when you start the container). Here's how to use the container with both Firefox & Chrome (install [Docker](https://docs.docker.com/engine/installation/) first).
 
+### Mac & Linux
+
 ~~~ bash
 $ docker pull sitespeedio/sitespeed.io
 $ docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io -b firefox
 ~~~
 
-## Windows
-We support Windows using [Docker](https://docs.docker.com/engine/installation/windows/). To be able to support running on Windows with NodeJS we need more [core contributors](/aboutus/) that can focus on Windows.
-
-### Docker
+### Windows
 
 ~~~ bash
 C:\Users\Vicky> docker pull sitespeedio/sitespeed.io
@@ -57,3 +36,29 @@ C:\Users\Vicky> docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.
 ~~~
 
 That will output the data from the run in the current directory. You can read more about running the containers [here](/documentation/sitespeed.io/docker/).
+
+## Standalone
+
+### Mac & Linux
+
+Prerequisites: Install [NodeJS 6.9.1 or newer](https://nodejs.org/en/download/) ([Linux](https://github.com/creationix/nvm)) and make sure you have [npm](https://github.com/npm/npm) or [yarn](https://yarnpkg.com/) installed.
+
+#### npm
+If you prefer npm, just run:
+
+~~~ bash
+$ npm install sitespeed.io -g
+$ sitespeed.io --help
+~~~
+
+#### yarn
+Or with [yarn](https://yarnpkg.com/):
+
+~~~ bash
+$ yarn global add sitespeed.io
+$ sitespeed.io --help
+~~~
+
+### Windows
+
+We support Windows using [Docker](https://docs.docker.com/engine/installation/windows/). To be able to support running on Windows with NodeJS we need more [core contributors](/aboutus/) that can focus on Windows.

docs/documentation/sitespeed.io/use-cases/index.md

@@ -18,7 +18,7 @@ twitterdescription: Use Cases for running sitespeed.io.
 ## Find performance problems in production
 One common use case is to crawl a site and analyze and measure the URLs. Crawling a site is good practice as it will find new pages that are linked from the pages you crawl.
 
-This is useful for sites where the content team creates new pages directly in a CMS and the developers don't have control over which pages exist. Crawling will make sure we pick up new pages and measure them. Use this to discover pages that could/should be faster or have problems.
+This is useful for sites where the content team creates new pages directly in a CMS and the developers don't have control over which pages will exist. Crawling will make sure we pick up new pages and measure them. Use this to discover pages that could/should be faster or have problems.
 
 Crawling too deep can take a considerable amount of time, so be aware.
 {: .note .note-warning}
@@ -27,20 +27,20 @@ Crawling too deep can take a considerable amount of time, so be aware.
 $ sitespeed.io http://www.nytimes.com/pages/sports/ -d 2
 ~~~
 
-Best practice is to not send crawl results to Graphite as it will probably create a lot of new URLS over time, making the size of the Graphite "database" grow indefinitely. Instead use it to verify deploys or that the content team following best practices. You can combine this with the [performance budget](../performance-budget/), making a test fail if any page crosses the limits.
+Best practice is to not send crawl results to Graphite as it will create a lot of new URLS over time, making the size of the Graphite "database" grow indefinitely. Instead use it to verify deploys or that the content team following best practices. You can combine this with the [performance budget](../performance-budget/), making a test fail if any page crosses the limits.
 
 ## Performance monitoring important URLs
 
-Testing the same URL over and over again is good practice, since this will allow you to benchmark it. This allows for continuous integration tool (to check the performance before changes is released) and when comparing sites to it's competitors (matching start pages, product pages, purchase flows, etc).
+Testing the same URL over and over again is good practice, since this will allow you to benchmark it. This allows for continuous integration tool (to check the performance before changes are released) and when comparing sites to it's competitors (matching start pages, product pages, purchase flows, etc).
 
 ### How to choose which URLs to test?
 
-If you use an Analytical tool check which pages are the most popular or talk to the business to check that you have the same understanding of which pages are the most important of the site.
+If you use an analytical tool, check which pages are the most popular or talk to the shareholders to determine that you have the same understanding of which pages are the most important to the business.
 
-If we going to test the URLss in our continuous integration, try to keep the list of URLs small, max of 10, so you can test each URL as many times as possible to get timings that are consistent between runs.
+If we going to test the URLs in our continuous integration, try to keep the list of URLs small, max of 10, so you can test each URL as many times as possible to get timings that are as consistent as possible between runs.
 
 ### What else do I need?
-You should do this continuously every X minutes/hours (depending how often you release/your content change). By default we support Graphite to store the data of a run and uses Grafana to make it look pretty.
+You should do this continuously every X minutes/hours (depending how often you release/your content change). We support Graphite and InfluxDB to store the data of a run and uses Grafana to make it look pretty. Here is an example setup using a text file, chrome with 5 runs and sending metrics to graphite.
 
 ### Setup
 
@@ -59,4 +59,4 @@ sitespeed.io amazon.txt -b chrome -n 5 --graphite.host my.graphite.host
 ~~~
 
 ## Find it before it reaches production
-Another way is to try to find problems before your code reached production. Do that by integrate sitespeed.io in [your continuous integration](../continuous-integration/).
+You can find problems before your code reached production by integrating sitespeed.io in [your continuous integration](../continuous-integration/).