From 698438863ced48fd04a195e35f3b1a47d7cbbfad Mon Sep 17 00:00:00 2001
From: Peter Hedenskog <peter@soulgalore.com>
Date: Fri, 10 Nov 2017 14:19:53 +0100
Subject: [PATCH] Introduction to sitespeed.io (#1791)

---
 HELP.md                                       | 23 -------
 docs/_includes/footer.html                    |  2 +-
 docs/_includes/index/box4.md                  |  2 +
 docs/_includes/index/install.md               |  2 +-
 .../2017-03-01-that-timeline-from-chrome.md   |  4 +-
 .../2017-04-03-releasing-with-confidence.md   |  2 +-
 docs/_posts/2017-04-24-sitespeed.io-5.0.md    |  4 +-
 docs/aboutus/index.md                         |  4 +-
 docs/documentation/browsertime/index.md       |  2 +-
 .../index.md                                  |  0
 .../sitespeed.io/getting-started/index.md     | 38 -----------
 docs/documentation/sitespeed.io/index.md      |  3 +-
 .../sitespeed.io/installation/index.md        |  2 +-
 .../sitespeed.io/introduction/index.md        | 60 ++++++++++++++++++
 .../sitespeed.io/use-cases/index.md           | 63 -------------------
 docs/important/index.md                       | 63 +++++++++++++++++++
 docs/version/pagexray.txt                     |  2 +-
 17 files changed, 138 insertions(+), 138 deletions(-)
 delete mode 100644 HELP.md
 rename docs/documentation/browsertime/{getting-started => introduction}/index.md (100%)
 delete mode 100644 docs/documentation/sitespeed.io/getting-started/index.md
 create mode 100644 docs/documentation/sitespeed.io/introduction/index.md
 delete mode 100644 docs/documentation/sitespeed.io/use-cases/index.md
 create mode 100644 docs/important/index.md

diff --git a/HELP.md b/HELP.md
deleted file mode 100644
index 4758ac3e0..000000000
--- a/HELP.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Help
-We want to make sitespeed.io the best web performance tool in the world and we hope you can to help us!
-
-## Developers
-We love to have more people involved in making sitespeed.io better. We are constantly working on adding more documentation and trying to write more information in the issues so its easier to help out. If there's an [issue](https://github.com/sitespeedio/sitespeed.io/issues) that you want to take on, ping the the issue and we can help you get started. You can also [join our Slack channel](https://sitespeedio.herokuapp.com/) if you need help!
-
-## Designers
-As a designer there's a lot you can do: You can make the HTML result pages look better. Maybe we should restructure the metrics? Maybe we should have graphs? Or could the header/footer look better? You could also have look at [https://www.sitespeed.io](https://www.sitespeed.io) where we have all the documentation. Make it look phab. You can pretty much help us with everything, no one in the core team got design skills :)
-
-## Documentation
-Documentation is fun and it is the core of making sitespeed.io easy to use. We got a [special documentation tag for issues](https://github.com/sitespeedio/sitespeed.io/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation) that you can use to find where we know we lack documentation. Fixing spelling mistakes is great. Or rewrite parts that you think is too complicated. You can find what you need to send a PR to the documentation [here](https://github.com/sitespeedio/sitespeed.io/tree/master/docs).
-
-## Tests
-We lack unit tests. You can read about [our testing pipeline](https://www.sitespeed.io/releasing-with-confidence/) that works good for us but more unit tests are always good. A good start is adding support for the code in the [support library](https://github.com/sitespeedio/sitespeed.io/tree/master/lib/support).
-
-
-## Companies
-Do you use sitespeed.io in your everyday work? Then we have a perfect proposition for you! Have a hack day with focus on sitespeed.io for your team and contribute back. Pick one the things in the **Help wanted** section. Or maybe there's a function you think is missing? Create it. Contribute back.
-
-# Help wanted
-You can help us:
-* [Add connectivity support](https://github.com/sitespeedio/browsertime/issues/313) for Android phones.
-* Help us make the documentation even better. We love your feedback and help [https://github.com/sitespeedio/sitespeed.io/tree/master/docs](https://github.com/sitespeedio/sitespeed.io/tree/master/docs).
diff --git a/docs/_includes/footer.html b/docs/_includes/footer.html
index e4d581bf2..04ffec91c 100644
--- a/docs/_includes/footer.html
+++ b/docs/_includes/footer.html
@@ -33,7 +33,7 @@
 		<h3>sitespeed.io</h3>
 		<ul>
 		<li><a href="{{site.baseurl}}/aboutus/">About Us</a></li>
-		<li><a href="https://github.com/sitespeedio/sitespeed.io/blob/master/HELP.md">Help Us</a></li>
+		<li><a href="{{site.baseurl}}/important/">Important - how we work</a></li>
 		<li><a href="https://dashboard.sitespeed.io/">The dashboard</a></li>
 		<li><a href="https://www.stickermule.com/marketplace/2574-sitespeed-dot-io">Stickers</a></li>
 		<li><a href="{{site.baseurl}}/logo/">Logos</a></li>
diff --git a/docs/_includes/index/box4.md b/docs/_includes/index/box4.md
index c79c88e64..91577f7ec 100644
--- a/docs/_includes/index/box4.md
+++ b/docs/_includes/index/box4.md
@@ -3,3 +3,5 @@
 We take your privacy really serious: Our [documentation site](https://www.sitespeed.io/), our [dashboard](https://dashboard.sitespeed.io) and our [compare tool](https://dashboard.sitespeed.io) do not use any tracking software at all (no Google Analytics or any other tracking software). None of the sitespeed.io tools call home.
 
 But beware: Chrome and Firefox can call home (we know for fact that Chrome do). We would love PRs and tips how to make sure browsers don't call home when you run your tests.
+
+[Read more]({{site.baseurl}}/important/) about how we do things.
diff --git a/docs/_includes/index/install.md b/docs/_includes/index/install.md
index c9ad70cdd..4b3babca2 100644
--- a/docs/_includes/index/install.md
+++ b/docs/_includes/index/install.md
@@ -1,7 +1,7 @@
 
 #### Docker
 
-Use our [Docker container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) to get an environment with Firefox, Chrome, XVFB and sitespeed.io up and running as fast as you can download them. They work [extremely well](({{site.baseurl}}/documentation/sitespeed.io/performance-dashboard/) ) together with Graphite/InfluxDB and Grafana.
+Use our [Docker container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) to get an environment with Firefox, Chrome, XVFB and sitespeed.io up and running as fast as you can download them. They work [extremely well]({{site.baseurl}}/documentation/sitespeed.io/performance-dashboard/) together with Graphite/InfluxDB and Grafana.
 
 ~~~bash
 docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io/
diff --git a/docs/_posts/2017-03-01-that-timeline-from-chrome.md b/docs/_posts/2017-03-01-that-timeline-from-chrome.md
index 78b8c00cd..60925049b 100644
--- a/docs/_posts/2017-03-01-that-timeline-from-chrome.md
+++ b/docs/_posts/2017-03-01-that-timeline-from-chrome.md
@@ -14,7 +14,7 @@ No that is not true! 4.5 got some awesome things that will help us all.
 ## New best practice for setting up connectivity
 As [reported](https://github.com/sitespeedio/browsertime/issues/271) by [Benedikt Christoph Wolters](https://github.com/worenga) the connectivity setup for tc for Docker wasn't perfect, it only added latency and limited upload. [Jonathan](https://twitter.com/beenanner) has created better way to do this by setting up Docker network bridges. Here's quick one on how you do that:
 
-~~~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
 tc qdisc add dev docker2 root handle 1: htb default 12
 tc class add dev docker2 parent 1:1 classid 1:12 htb rate 5mbit ceil 5mbit
@@ -24,7 +24,7 @@ tc qdisc add dev docker2 parent 1:12 netem delay 28ms
 You then have network called cable that you can use from your Docker container by adding <code>--network=cable</code> to your Docker commands.
 
 ~~~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 --browsertime.connectivity.engine external https://www.sitespeed.io/
 ~~~
 
 You have more examples [here]({{site.baseurl}}/documentation/sitespeed.io/browsers/#change-connectivity) and would love feedback and PRs on how to do the same on platforms not supporting tc.
diff --git a/docs/_posts/2017-04-03-releasing-with-confidence.md b/docs/_posts/2017-04-03-releasing-with-confidence.md
index 4c98828f4..51235b3e8 100644
--- a/docs/_posts/2017-04-03-releasing-with-confidence.md
+++ b/docs/_posts/2017-04-03-releasing-with-confidence.md
@@ -65,7 +65,7 @@ When we release (= a new version to npm and a new tag to the Docker hub) we use
 If you use Docker (and you should) make sure that you run a tagged versions and by tag we don't mean latest. Pull by setting the version number just like this:
 
 ~~~bash
-$ docker pull sitespeedio/sitespeed.io:4.7.0
+docker pull sitespeedio/sitespeed.io:4.7.0
 ~~~
 
 When you upgrade, read the [changelog](https://github.com/sitespeedio/sitespeed.io/blob/master/CHANGELOG.md) and Docker pull the new version and then change your run script/yml file (or whatever you use to start sitespeed.io) so that it matches the new version number.
diff --git a/docs/_posts/2017-04-24-sitespeed.io-5.0.md b/docs/_posts/2017-04-24-sitespeed.io-5.0.md
index ee9245086..9cc0627ea 100644
--- a/docs/_posts/2017-04-24-sitespeed.io-5.0.md
+++ b/docs/_posts/2017-04-24-sitespeed.io-5.0.md
@@ -107,13 +107,13 @@ We have finally been able to add support for your own request headers as well as
 Adding a request header:
 
 ~~~bash
-$ docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io/ -r Name:Value
+docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io/ -r Name:Value
 ~~~
 
 Blocking all request on my.example.com:
 
 ~~~bash
-$ docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io/ --block my.example.com
+docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io/ --block my.example.com
 ~~~
 
 ## Non backward compatible changes in 5.0
diff --git a/docs/aboutus/index.md b/docs/aboutus/index.md
index d4463c4e6..be9b172f3 100644
--- a/docs/aboutus/index.md
+++ b/docs/aboutus/index.md
@@ -12,7 +12,7 @@ nav: aboutus
 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.  
+<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.
 
 As a performance engineer at [CBSi](http://www.cbsinteractive.com/) I am able to offer real-world feedback to the team to make improvements that will benefit others.  I love talking about web performance so feel free connect or reach out to me on [LinkedIn](https://www.linkedin.com/in/jonathanlee20) or [Twitter](https://twitter.com/beenanner).
 
@@ -25,6 +25,6 @@ In my work at [iZettle](https://www.izettle.com/) I spend most of my time enabli
 ## Peter Hedenskog
 <a href="https://twitter.com/soulislove"><img src="{{site.baseurl}}/img/aboutus/peter.jpg" class="photo pull-left" width="200" height="200"></a>  I created sitespeed.io late 2012. It's been a lot of work and incredibly [fun](http://www.peterhedenskog.com/blog/2015/02/building-a-new-sitespeed.io/)! I'm a web performance geek, love the web and think Open Source is the way forward. I work in the performance team at [Wikimedia](https://www.wikimedia.org/).
 
-In early 2015 I was awarded for building sitespeed.io by [The Swedish Internet Infrastructure Foundation](https://www.iis.se/english/about-se/) making it possible for me to work full time on the project for three months.
+In early 2015 I was awarded for building sitespeed.io by [The Swedish Internet Infrastructure Foundation](https://www.iis.se/english/about-iis/) making it possible for me to work full time on the project for three months.
 
 I'm one of the organizers of the [Stockholm Web Performance meetup group](http://www.meetup.com/Stockholm-Web-Performance-Group/). We are 700+ members and are always looking for new speakers. If you are in Stockholm and have something to share, ping me on <a href="https://twitter.com/soulislove">Twitter</a> and see if we can make it happen.
diff --git a/docs/documentation/browsertime/index.md b/docs/documentation/browsertime/index.md
index 9410af4f4..21414bafe 100644
--- a/docs/documentation/browsertime/index.md
+++ b/docs/documentation/browsertime/index.md
@@ -15,7 +15,7 @@ twitterdescription: Documentation for Browsertime.
 
 Browsertime is the heart of sitespeed.io that handles everything with the browser. At the moment we support Chrome and Firefox on desktop and Chrome on Android. But we want to [support Opera (on Android)](https://github.com/sitespeedio/browsertime/issues/150)  and when(?!) iOS Safari supports WebDriver we will add that too. You can see all the latest changes in the [Changelog](https://github.com/sitespeedio/browsertime/blob/master/CHANGELOG.md) for the project.
 
- * [Getting started](getting-started/) - what you can do with Browsertime.
+ * [Introduction](introduction/) - what you can do with Browsertime.
  * [Installation](installation/) - install using npm, yarn or run our Docker containers.
  * [Configuration](configuration/) - there's a lot of things you can do with Browsertime.
  * [More details](details/) - lets checkout how everything works.
diff --git a/docs/documentation/browsertime/getting-started/index.md b/docs/documentation/browsertime/introduction/index.md
similarity index 100%
rename from docs/documentation/browsertime/getting-started/index.md
rename to docs/documentation/browsertime/introduction/index.md
diff --git a/docs/documentation/sitespeed.io/getting-started/index.md b/docs/documentation/sitespeed.io/getting-started/index.md
deleted file mode 100644
index 250626451..000000000
--- a/docs/documentation/sitespeed.io/getting-started/index.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-layout: default
-title: Getting Started
-description: Introduction for sitespeed.io.
-keywords: introduction, getting started, documentation, web performance, sitespeed.io
-nav: documentation
-category: sitespeed.io
-image: https://www.sitespeed.io/img/sitespeed-2.0-twitter.png
-twitterdescription: Introduction for sitespeed.io.
----
-[Documentation](/documentation/sitespeed.io/) / Getting Started
-
-# Getting Started
-{:.no_toc}
-
-* Let's place the TOC here
-{:toc}
-
-Sitespeed.io is an Open Source tool that helps you measuring the performance of your website. You can [install](../installation/) it using [npm](https://www.npmjs.org/)/[yarn](https://yarnpkg.com/)/[Docker](https://www.docker.com/). The first version was released 2012.
-
-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; check out 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 any way you can imagine.
-
-In December 2017 we released 6.0 (sitespeed.io has been around for 5 years).  With 3.X we got the following feedback in the [Toolsday](http://www.toolsday.io/) podcast:
-
-<blockquote cite="http://www.toolsday.io/episodes/performance.html">
-SpeedCurve has a really low barrier of entry ... it's a bit of a evolution maybe ... if you need something more advanced look into sitespeed.io"
- <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 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!
diff --git a/docs/documentation/sitespeed.io/index.md b/docs/documentation/sitespeed.io/index.md
index a38250395..da53a26b8 100644
--- a/docs/documentation/sitespeed.io/index.md
+++ b/docs/documentation/sitespeed.io/index.md
@@ -15,12 +15,11 @@ twitterdescription: Documentation for sitespeed.io.
 
 Sitespeed.io is the complete toolbox to test the web performance of your web site. Use it to monitor your performance or checkout how your competition is doing. First version was created 2012 and been running on Linux since then. You can see all the latest changes in the [Changelog](https://github.com/sitespeedio/sitespeed.io/blob/master/CHANGELOG.md) for the project.
 
- * [Getting started](getting-started/) - get up and running with sitespeed.io
+ * [Introduction](introduction/) - start here if you are new to the project or web performance testing.
  * [Installation](installation/) - install using npm, yarn or run our Docker containers.
  * [Configuration](configuration/) - there's a lot of things you can do with sitespeed.io, lets checkout how!
  * [Browsers](browsers/) - collect timings using real browsers. We support Firefox, Chrome and Chrome on Android.
  * [Connectivity](connectivity/) - set the connectivity to emulate real users network conditions.
- * [Use Cases](use-cases/) - find out best practices for testing a site, compare with other sites.
  * [Performance Dashboard](performance-dashboard/) - keep track of your metrics and performance.
  * [Alerts](alerts/) - send alerts (email/Slack/PagerDuty etc) when you get a performance regression.
  * [F.A.Q and Best Practice](best-practice/) - here we keep track of questions we get in Slack.
diff --git a/docs/documentation/sitespeed.io/installation/index.md b/docs/documentation/sitespeed.io/installation/index.md
index 66922ec40..3a8cb6380 100644
--- a/docs/documentation/sitespeed.io/installation/index.md
+++ b/docs/documentation/sitespeed.io/installation/index.md
@@ -38,7 +38,7 @@ 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
+## Node JS
 
 ### Mac & Linux
 
diff --git a/docs/documentation/sitespeed.io/introduction/index.md b/docs/documentation/sitespeed.io/introduction/index.md
new file mode 100644
index 000000000..ed0ec92ff
--- /dev/null
+++ b/docs/documentation/sitespeed.io/introduction/index.md
@@ -0,0 +1,60 @@
+---
+layout: default
+title: Introduction to sitespeed.io and web performance testing
+description: Start here if you are new to sitespeed.io or web performance testing.
+keywords: introduction, getting started, documentation, web performance, sitespeed.io
+nav: documentation
+category: sitespeed.io
+image: https://www.sitespeed.io/img/sitespeed-2.0-twitter.png
+twitterdescription: Introduction for sitespeed.io.
+---
+[Documentation](/documentation/sitespeed.io/) / Introduction
+
+# Introduction
+{:.no_toc}
+
+* Let's place the TOC here
+{:toc}
+
+**Sitespeed.io is a *complete web performance tool* that helps you measure the performance of your website. What exactly does that mean?**
+
+We think of a complete web performance tool as having three key capabilities:
+
+ - It test web sites using real browsers, simulating real users connectivity and collect important user centric metrics like Speed Index and First Visual Render.
+ - It analyse how your page is built and give feedback how you can make it faster for the end user.
+ - It collect and keep data how your pages is built so you easily can track changes.
+
+**What is sitespeed.io good for?**
+
+It is usually used in two different areas:
+
+ - Running in your continuous integration to find web performance regressions early: on commits or when you move code to your test environment
+ - Monitoring your performance in production, alerting on regressions.
+
+To understand how sitespeed.io does these things, let's talk about how it works.
+
+First a few key concepts:
+
+ - Sitespeed.io is built upon a couple of other Open Source tools in the sitespeed.io suite.
+ - [Browsertime](../../browsertime/) is the tool that drives the browser and collect metrics.
+ - [The Coach](../../coach/) knows how to build fast websites and analyse your page and give you feedback what you should change.
+ - Visual Metrics is metrics collected from a video recording of the browser screen.
+ - Everything in sitespeed.io is a [plugin](../plugins/) and they communicate by passing messages on a queue.
+
+When you as user choose to test a URL, this is what happens on a high level:
+
+ 1. sitespeed.io starts and initialise all configured plugins.
+ 2. The URL is passed around the plugins through the queue.
+    1. Browsertime gets the URL and opens the browser.
+    2. It starts to record a video of the browser screen.
+    3. The browser access the URL.
+    4. When the page is finished, Browsertime takes a screenshot of the page.
+    5. Then run some JavaScripts to analyse the page (using Coach and Browsertime scripts).
+    6. Stop the video and close the browser.
+    7. Analyse the video to get Visual Metrics like First Visual Change and Speed Index.
+    8. Browsertime passes all metrics and data on the queue so other plugins can use it.
+ 3. The HTML/Graphite/InfluxDB plugin collects the metrics in queue.
+ 4. When all URLs are tested, sitespeed sends a message telling plugins to summarise the metrics and then render it
+ 5. Plugins pickup the render message and the HTML plugin writes the HTML to disk
+
+Now it's time for you to [install and run sitespeed.io](../installation/).
diff --git a/docs/documentation/sitespeed.io/use-cases/index.md b/docs/documentation/sitespeed.io/use-cases/index.md
deleted file mode 100644
index 7803b5f0c..000000000
--- a/docs/documentation/sitespeed.io/use-cases/index.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-layout: default
-title: Use Cases for using sitespeed.io
-description: Use Cases for running sitespeed.io.
-keywords: use case, documentation, web performance, sitespeed.io
-nav: documentation
-category: sitespeed.io
-image: https://www.sitespeed.io/img/sitespeed-2.0-twitter.png
-twitterdescription: Use Cases for running sitespeed.io.
----
-[Documentation]({{site.baseurl}}/documentation/sitespeed.io/) / Use Cases
-
-# Use Cases
-{:.no_toc}
-
-* Lets place the TOC here
-{:toc}
-
-## 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 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}
-
-~~~bash
-docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io http://www.nytimes.com/pages/sports/ -d 2
-~~~
-
-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 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 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 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). 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
-
-Create a text file named amazon.txt with all the URL:s
-
-~~~
-http://www.amazon.com/
-http://www.amazon.com/gp/site-directory/
-http://www.amazon.com/dp/B00I15SB16/ref=ods_gw_comb_xmas_kindle
-~~~
-
-And run it like this
-
-~~~bash
-docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io amazon.txt -b chrome -n 5 --graphite.host my.graphite.host
-~~~
-
-## Find it before it reaches production
-You can find problems before your code reached production by integrating sitespeed.io in [your continuous integration](../continuous-integration/).
diff --git a/docs/important/index.md b/docs/important/index.md
new file mode 100644
index 000000000..71c033066
--- /dev/null
+++ b/docs/important/index.md
@@ -0,0 +1,63 @@
+---
+layout: default
+title: Important information on how we work in sitespeed.io and related projects.
+description: Start here if you are new to sitespeed.io or web performance testing.
+keywords: introduction, getting started, documentation, web performance, sitespeed.io
+nav: documentation
+category: sitespeed.io
+image: https://www.sitespeed.io/img/sitespeed-2.0-twitter.png
+twitterdescription: Introduction for sitespeed.io.
+---
+
+# Important
+{:.no_toc}
+
+* Let's place the TOC here
+{:toc}
+
+## How we work
+A couple of important things to know about our projects:
+
+ - We always keep a CHANGELOG in the root of directory of the project. [Here's](https://github.com/sitespeedio/sitespeed.io/blob/master/CHANGELOG.md) the one we have for sitespeed.io. We always write down the changes we do in the project.
+ - We always use [semantic versioning](http://semver.org/) when we do a release.
+ - We try to release things as soon as the functionality is tested and ready (we release often). For sitespeed.io we try to do one major release each year.
+ - We highly rely on testing on [Travic-CI](https://travis-ci.org/) and our [own automatic testing](https://www.sitespeed.io/releasing-with-confidence/).
+
+## Privacy
+
+We take your privacy really serious: Our [documentation site](https://www.sitespeed.io/), our [dashboard](https://dashboard.sitespeed.io) and our [compare tool](https://dashboard.sitespeed.io) do not use any tracking software at all (no Google Analytics or any other tracking software). None of the sitespeed.io tools call home.
+
+But beware: Chrome and Firefox can call home (we know for fact that Chrome do). We would love PRs and tips how to make sure browsers don't call home when you run your tests.
+
+## Code of Conduct
+When you create issues, do PRs, use our Slack channel or contact us on email, please follow our [Code Of Conduct](https://github.com/sitespeedio/sitespeed.io/blob/master/CODE_OF_CONDUCT.md).
+
+## Open Source
+We release our software under the [MIT License](https://github.com/sitespeedio/sitespeed.io/blob/master/LICENSE). Please respect it and respect our work: We ask you not to change the logo or the contribution to the project. Please do this to pay the respect to the many hours we put down into the project.
+
+## Sustainability
+We've been releasing sitespeed.io since 2012 and we plan to continue do it for a long time. At the moment we are a [three member team](../aboutus/) and we love to get more people involved!
+
+We work on the project after hours and usually that is enough to keep it going. Peter has been taking a couple of weeks off work each year to prepare for larger releases.
+
+We have stayed away from taking money contributions so far (except an award from the [The Swedish Internet Infrastructure Foundation](https://www.iis.se/english/about-iis/)). That helps us to be independent (and that is important for us), but we aren't totally closing the door for money. But we prefer people helping out with PRs instead.
+
+## We wants to help you
+We really (yes I mean really) focus on helping you as a user. If you have a problem please [create an issue](https://github.com/sitespeedio/sitespeed.io/issues/new) or talk to us on our [Slack channel](https://sitespeedio.herokuapp.com/).
+
+If there's a common problem or a bug and we talk about it on Slack we will kindly ask you to create an issue. Issues are great because it helps people that has the same problem.
+
+It sometimes happens that we get get contacted about issues privately via email or DM on Twitter. Please don't do that, we want to keep everything as open as possible. Only contact us if we ask you to or if you have an important security issue.
+
+## Who uses sitespeed.io
+
+We had over one million downloads so far and still counting. We have companies in the Alexa top 10 that uses we sitespeed.io. We have students at the university that uses our tools. We are pretty sure sitespeed.io will work out good for you too.
+
+With the old 3.X we got the following feedback in the [Toolsday](http://www.toolsday.io/) podcast:
+
+<blockquote cite="http://www.toolsday.io/episodes/performance.html">
+SpeedCurve has a really low barrier of entry ... it's a bit of a evolution maybe ... if you need something more advanced look into sitespeed.io"
+ <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](../documentation/sitespeed.io/webpagetest/) using sitespeed.io and collect the metrics and use it side by side with all the sitespeed.io metrics.
diff --git a/docs/version/pagexray.txt b/docs/version/pagexray.txt
index 7dea76edb..227cea215 100644
--- a/docs/version/pagexray.txt
+++ b/docs/version/pagexray.txt
@@ -1 +1 @@
-1.0.1
+2.0.0