diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md
index 8a3940056..d427a2080 100644
--- a/docs/guides/debugging.md
+++ b/docs/guides/debugging.md
@@ -12,7 +12,7 @@
 
 ## Logging
 
-Video.js includes a lightweight wrapper - `videojs.log` - around a subset of [the `console` API][console]. The available methods are `videojs.log`, `videojs.log.warn`, and `videojs.log.error`.
+Video.js includes `videojs.log`, a lightweight wrapper around a subset of [the `console` API][console]. The available methods are `videojs.log`, `videojs.log.warn`, and `videojs.log.error`.
 
 ### API Overview
 
diff --git a/docs/guides/event-target.md b/docs/guides/event-target.md
index d66a43b3a..9b0d3de0a 100644
--- a/docs/guides/event-target.md
+++ b/docs/guides/event-target.md
@@ -10,7 +10,7 @@
 
 ## Overview
 
-Events in video.js are setup so that they mimic the DOM API that is used on object, but also have helpful shorthand functions with the same functionality.
+Events in Video.js are setup so that they mimic the DOM API that is used on object, but also have helpful shorthand functions with the same functionality.
 
 ## `on()` and `addEventListener()`
 
diff --git a/docs/guides/faq.md b/docs/guides/faq.md
index 373a0c01c..c2032b3e3 100644
--- a/docs/guides/faq.md
+++ b/docs/guides/faq.md
@@ -2,109 +2,112 @@
 
 ## Table of Contents
 
-* [Q: What is video.js?](#q-what-is-videojs)
-* [Q: How do I install video.js?](#q-how-do-i-install-videojs)
-* [Q: Is video.js on bower?](#q-is-videojs-on-bower)
-* [Q: What do video.js version numbers mean?](#q-what-do-videojs-version-numbers-mean)
+* [Q: What is Video.js?](#q-what-is-videojs)
+* [Q: How do I install Video.js?](#q-how-do-i-install-videojs)
+* [Q: Is Video.js on bower?](#q-is-videojs-on-bower)
+* [Q: What do Video.js version numbers mean?](#q-what-do-videojs-version-numbers-mean)
 * [Q: How can I troubleshoot playback issues?](#q-how-can-i-troubleshoot-playback-issues)
 * [Q: A video does not play in a specific browser. Why?](#q-a-video-does-not-play-in-a-specific-browser-why)
 * [Q: Why does the entire video download before playback? Why does the video load for a long time?](#q-why-does-the-entire-video-download-before-playback-why-does-the-video-load-for-a-long-time)
 * [Q: I see an error thrown that mentions vdata12345. What is that?](#q-i-see-an-error-thrown-that-mentions-vdata12345-what-is-that)
-* [Q: I think I found a bug with video.js or I want to add a feature. What should I do?](#q-i-think-i-found-a-bug-with-videojs-or-i-want-to-add-a-feature-what-should-i-do)
+* [Q: I think I found a bug with Video.js or I want to add a feature. What should I do?](#q-i-think-i-found-a-bug-with-videojs-or-i-want-to-add-a-feature-what-should-i-do)
   * [if you think that you can fix the issue or add the feature](#if-you-think-that-you-can-fix-the-issue-or-add-the-feature)
   * [If you don't think you can fix the issue or add the feature](#if-you-dont-think-you-can-fix-the-issue-or-add-the-feature)
 * [Q: What is a reduced test case?](#q-what-is-a-reduced-test-case)
-* [Q: What media formats does video.js support?](#q-what-media-formats-does-videojs-support)
+* [Q: What media formats does Video.js support?](#q-what-media-formats-does-videojs-support)
+* [Q: How does Video.js choose which source to use?](#q-how-does-videojs-choose-which-source-to-use)
 * [Q: How to I autoplay the video?](#q-how-to-i-autoplay-the-video)
   * [Q: How can I autoplay a video on a mobile device?](#q-how-can-i-autoplay-a-video-on-a-mobile-device)
-* [Q: How can I play RTMP video in video.js?](#q-how-can-i-play-rtmp-video-in-videojs)
+* [Q: How can I play RTMP video in Video.js?](#q-how-can-i-play-rtmp-video-in-videojs)
 * [Q: How can I hide the links to my video/subtitles/audio/tracks?](#q-how-can-i-hide-the-links-to-my-videosubtitlesaudiotracks)
-* [Q: Can I turn off video.js logging?](#q-can-i-turn-off-videojs-logging)
+* [Q: Can I turn off Video.js logging?](#q-can-i-turn-off-videojs-logging)
 * [Q: What is a plugin?](#q-what-is-a-plugin)
-* [Q: How do I make a plugin for video.js?](#q-how-do-i-make-a-plugin-for-videojs)
-* [Q: Where can I find a list of video.js plugins?](#q-where-can-i-find-a-list-of-videojs-plugins)
+* [Q: How do I make a plugin for Video.js?](#q-how-do-i-make-a-plugin-for-videojs)
+* [Q: Where can I find a list of Video.js plugins?](#q-where-can-i-find-a-list-of-videojs-plugins)
 * [Q: How can I get my plugin listed on the website?](#q-how-can-i-get-my-plugin-listed-on-the-website)
-* [Q: Where can I find a list of video.js skins?](#q-where-can-i-find-a-list-of-videojs-skins)
-* [Q: Does video.js work as an audio only player?](#q-does-videojs-work-as-an-audio-only-player)
-* [Q: Does video.js support audio tracks?](#q-does-videojs-support-audio-tracks)
-* [Q: Does video.js support video tracks?](#q-does-videojs-support-video-tracks)
-* [Q: Does video.js support text tracks (captions, subtitles, etc)?](#q-does-videojs-support-text-tracks-captions-subtitles-etc)
-* [Q: Does video.js support HLS (HTTP Live streaming) video?](#q-does-videojs-support-hls-http-live-streaming-video)
-* [Q: Does video.js support MPEG Dash video?](#q-does-videojs-support-mpeg-dash-video)
-* [Q: Does video.js support live video?](#q-does-videojs-support-live-video)
-* [Q: Can video.js wrap around YouTube videos?](#q-can-videojs-wrap-around-youtube-videos)
-* [Q: Can video.js wrap around Vimeo videos?](#q-can-videojs-wrap-around-vimeo-videos)
-* [Q: Does video.js support DRM video?](#q-does-videojs-support-drm-video)
-* [Q: Does video.js have any support for advertisement integrations?](#q-does-videojs-have-any-support-for-advertisement-integrations)
-* [Q: Can video.js be required in node.js?](#q-can-videojs-be-required-in-nodejs)
-* [Q: Does video.js work with webpack?](#q-does-videojs-work-with-webpack)
-* [Q: Does video.js work with react?](#q-does-videojs-work-with-react)
+* [Q: Where can I find a list of Video.js skins?](#q-where-can-i-find-a-list-of-videojs-skins)
+* [Q: Does Video.js work as an audio only player?](#q-does-videojs-work-as-an-audio-only-player)
+* [Q: Does Video.js support audio tracks?](#q-does-videojs-support-audio-tracks)
+* [Q: Does Video.js support video tracks?](#q-does-videojs-support-video-tracks)
+* [Q: Does Video.js support text tracks (captions, subtitles, etc)?](#q-does-videojs-support-text-tracks-captions-subtitles-etc)
+* [Q: Does Video.js support HLS (HTTP Live streaming) video?](#q-does-videojs-support-hls-http-live-streaming-video)
+* [Q: Does Video.js support MPEG Dash video?](#q-does-videojs-support-mpeg-dash-video)
+* [Q: Does Video.js support live video?](#q-does-videojs-support-live-video)
+* [Q: Can Video.js wrap around YouTube videos?](#q-can-videojs-wrap-around-youtube-videos)
+* [Q: Can Video.js wrap around Vimeo videos?](#q-can-videojs-wrap-around-vimeo-videos)
+* [Q: Does Video.js support DRM video?](#q-does-videojs-support-drm-video)
+* [Q: Does Video.js have any support for advertisement integrations?](#q-does-videojs-have-any-support-for-advertisement-integrations)
+* [Q: Can Video.js be required in node.js?](#q-can-videojs-be-required-in-nodejs)
+* [Q: Does Video.js work with webpack?](#q-does-videojs-work-with-webpack)
+* [Q: Does Video.js work with react?](#q-does-videojs-work-with-react)
 
-## Q: What is video.js?
+## Q: What is Video.js?
 
-video.js is an extendable framework/library around the native video element. It does the following:
+Video.js is an extendable framework/library around the native video element. It does the following:
 
 * Offers a plugin API so that different types of video can be handed to the native
   video element (e.g. [HLS][hls], [Flash][flash], HTML5 video, etc).
-* Unifies the native video api across browsers (polyfilling support for features
+* Unifies the native video API across browsers (polyfilling support for features
   if necessary)
 * Offers an extendable and themable UI
-* Takes care of accessibility for the user (in-progress)
-* Has a set of core plugins that offer support for tons of additional video formats.
+* Ensures accessibility for keyboard and screen reader users
+* Has a set of core plugins that offer support for additional video formats:
   * [videojs-contrib-hls][hls]
   * [videojs-contrib-dash][dash]
-* Support for DRM video via a core plugin
+* Supports  DRM video via a core plugin:
   * [videojs-contrib-eme][eme]
-* Lots of plugins which offer support for all kinds of features. See the [plugin list on videojs.com][plugin-list]
+* Is extensible with lots of plugins offering support for all kinds of features. See the [plugin list on videojs.com][plugin-list]
 
-## Q: How do I install video.js?
+## Q: How do I install Video.js?
 
-Currently video.js can be installed using npm, serving a release file from
-a github tag, or even using a CDN hosted version. For information on doing any of those
-see the [install guide][install-guide].
+Currently Video.js can be installed using npm, serving a release file from
+a GitHub tag, or even using a CDN hosted version. For information on doing any of those
+see the [setup guide][install-guide].
 
-## Q: Is video.js on bower?
+## Q: Is Video.js on bower?
 
-Versions prior to video.js 6 do support bower, however, as of video.js 6, bower is no
+Versions prior to Video.js 6 support bower, however, as of Video.js 6, bower is no
 longer officially supported. Please see https://github.com/videojs/video.js/issues/4012
 for more information.
 
-## Q: What do video.js version numbers mean?
+## Q: What do Video.js version numbers mean?
 
-video.js follows [semver][semver] which means that the API should not change
+Video.js follows [semver][semver] which means that the API should not change
 out from under a user unless there is a major version increase.
 
 ## Q: How can I troubleshoot playback issues?
 
 See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
-solve your issue, please submit a [pull request or an issue][pr-issue-question].
+solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
+
+When seeking help about a playback issue the problem is often specific to the video file used, the way the video is hosted or the browser, so make sure to include all of that information and a [reduced test case](#q-what-is-a-reduced-test-case).
 
 ## Q: A video does not play in a specific browser. Why?
 
 See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
-solve your issue, please submit a [pull request or an issue][pr-issue-question].
+solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
 
 ## Q: Why does the entire video download before playback? Why does the video load for a long time?
 
 See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
-solve your issue, please submit a [pull request or an issue][pr-issue-question].
+solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
 
 ## Q: I see an error thrown that mentions `vdata12345`. What is that?
 
 See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
-solve your issue, please submit a [pull request or an issue][pr-issue-question].
+solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
 
-## Q: I think I found a bug with video.js or I want to add a feature. What should I do?
+## Q: I think I found a bug with Video.js or I want to add a feature. What should I do?
 
-### if you think that you can fix the issue or add the feature
+### If you think that you can fix the issue or add the feature
 
-Submit a pull request to the [video.js repo][vjs-prs].
+A pull request would be very welcome in the [Video.js repo][vjs-prs].
 Make sure to follow the [contributing guide][contributing-prs] and
 the [pull request template][pr-template].
 
 ### If you don't think you can fix the issue or add the feature
 
-Open an [issue on the video.js repo][vjs-issues]. Make
+Open an [issue on the Video.js repo][vjs-issues]. Make
 sure that you follow the [issue template][issue-template] and the
 [contributing guide][contributing-issues] so that we can better assist you
 with your issue.
@@ -113,18 +116,28 @@ with your issue.
 
 A reduced test case is an example of the problem that you are facing in isolation.
 Think of it as example page that reproduces the issue in the least amount of possible code.
+
+It's important to add a reduced case. Even if the problem seems obvious it may not be to
+others. Having a example to refer to also makes the difference between somebody being able
+to take a look and immediately see what's wrong, and needing to take time to recreate what
+they think you are describing.
+
 We have a [starter example][starter-example] for reduced test cases. To learn more
 about reduced test cases visit [css-tricks][reduced-test-case]
 
-## Q: What media formats does video.js support?
+## Q: What media formats does Video.js support?
 
 This depends on the formats supported by the browser's HTML5 video element, and the playback
-techs/plugins made available to video.js. For more information on media formats see the [troubleshooting guide][troubleshooting].
+techs/plugins made available to Video.js. For more information on media formats see the [troubleshooting guide][troubleshooting].
+
+## Q: How does Video.js choose which source to use?
+
+When an array of sources is available, Video.js test each source in the order given. For each source, each tech in the [`techOrder`][techorder] will be checked to see if it can play it whether directly or via source handler (such as videojs-contrib-hls). The first match will be chosen.
 
 ## Q: How to I autoplay the video?
 
 Video.js supports the standard html5 `autoplay` attribute on the video element.
-It also supports it as an option to video.js or as a method invocation on the player.
+It also supports it as an option to Video.js or as a method invocation on the player.
 
 ```html
 <video autoplay controls class="video-js">
@@ -143,7 +156,7 @@ player.autoplay(true);
 ### Q: How can I autoplay a video on a mobile device?
 
 Most mobile devices have blocked autoplaying videos until recently.
-For mobile devices that don't support autoplaying, autoplay isn't supported by video.js.
+For mobile devices that don't support autoplaying, autoplay isn't supported by Video.js.
 For those devices that support autoplaying, like iOS10 and Chrome for Android 53+,
 you must mute the video or have a video without audio tracks to be able to play it.
 For example:
@@ -154,23 +167,28 @@ For example:
 
 Will make an inline, muted, autoplaying video on an iPhone with iOS10.
 
-## Q: How can I play RTMP video in video.js?
+## Q: How can I play RTMP video in Video.js?
 
-Make sure that the Flash tech is available -- RTMP is not playable on browsers without Flash including mobile. Flash will only be available on video.js 6 with the [videojs-flash package][flash], in previous versions it was builtin to video.js. Then, just set the rtmp source with an appropriate type -- `rtmp/mp4` or `rtmp/flv`.
-The main thing to be aware of is that video.js splits the connection url and stream name with the `&` character.
-So, you'd want to update the url to follow that format. For example: `rtmp://example.com/live&foo` or `rtmp://example.com/fms&mp4:path/to/file.mp4`.
+RTMP requires Flash to play back. You'll need both a browser that supports Flash and the Flash tech.
 
-If the server requires query parameters for authentication, these should be added to the connection part url, for example `rtmp://example.com/live?token=1234&foo`.
+In Video.js version 6, the Flash tech is not included by default and is available as a separate [videojs-flash package][flash]. In previous versions it was builtin to Video.js.
+
+The RTMP source should be set with an appropriate type -- `rtmp/mp4` or `rtmp/flv`.
+Be aware of that Video.js splits the connection url and stream name with the `&` character, for example: `rtmp://example.com/live&foo` or `rtmp://example.com/fms&mp4:path/to/file.mp4`.
+
+If the server requires query parameters for authentication, these should be added to the connection part URL, for example `rtmp://example.com/live?token=1234&foo`.
+
+Bear in mind that mobile browsers do not support Flash, and modern desktop browsers make it increasingly difficult to use Flash or disable it by default for your end users. Consider moving to a modern format such as HLS or DASH.
 
 ## Q: How can I hide the links to my video/subtitles/audio/tracks?
 
 It's impossible to hide the network requests a browser makes and difficult to
 sufficiently obfuscate URLs in the source. Techniques such as token authentication may
-help but are outside of the scope of video.js.
+help but are outside of the scope of Video.js.
 
 For content that must be highly secure [videojs-contrib-eme][eme] adds DRM support.
 
-## Q: Can I turn off video.js logging?
+## Q: Can I turn off Video.js logging?
 
 Yes! This can be achieved by adding the following code _after_ including Video.js, but _before_ creating any player(s):
 
@@ -183,21 +201,19 @@ For more information, including which logging levels are available, check out th
 ## Q: What is a plugin?
 
 A plugin is a group of reusable functionality that can be re-used by others. For instance a plugin could add
-a button to video.js that makes the video replay 10 times in a row before it stops playback for good. If such
+a button to Video.js that makes the video replay 10 times in a row before it stops playback for good. If such
 a plugin existed and was published users could include it on their page to share that functionality.
 
-## Q: How do I make a plugin for video.js?
+## Q: How do I make a plugin for Video.js?
 
-See the [plugin guide][plugin-guide] for information on making a plugin for video.js.
+See the [plugin guide][plugin-guide] for information on making a plugin for Video.js.
 
-<!-- TODO: Once these is a button guide, add this back in
-## Q: How do I add a button to video.js?
-See the [button guide][button-guide] for information on adding a button to video.js.
--->
+## Q: How do I add a button to Video.js?
+See the [components guide][components-guide] for an example of adding a button to Video.js.
 
-## Q: Where can I find a list of video.js plugins?
+## Q: Where can I find a list of Video.js plugins?
 
-The official [list of plugins on videojs.com][plugin-list].
+A list of plugins published to npm with the `videojs-plugin` keyword is maintained [on videojs.com][plugin-list].
 
 ## Q: How can I get my plugin listed on the website?
 
@@ -205,72 +221,73 @@ Add the 'videojs-plugin' [keyword to your array in package.json][npm-keywords]
 and publish your package to npm. If you use the [plugin generator][generator] this will be done automatically for you. See
 the [plugins guide][plugin-guide] for more information.
 
-## Q: Where can I find a list of video.js skins?
+## Q: Where can I find a list of Video.js skins?
 
-See the [video.js github wiki][skins-list].
+See the [Video.js GitHub wiki][skins-list].
 
-## Q: Does video.js work as an audio only player?
+## Q: Does Video.js work as an audio only player?
 
-Yes! It can be used to play audio only files in a `<video>` or `<audio>` tag. The
-difference being that the `<audio>` tag will not have a blank display area and the `<video>`
-tag will. Note that audio only will not work with the Flash playback tech. The Flash playback tech will only be included in versions of video.js before 6. In Video.js 6 you will need to use the [videojs-flash package][flash].
+Yes! It can be used to play audio only files in a `<video>` or `<audio>` tag.
+Note that audio-only sources do not work with the Flash playback tech.
 
-## Q: Does video.js support audio tracks?
+## Q: Does Video.js support audio tracks?
 
 Yes! See the [audio tracks guide][audio-tracks] for information on using audio tracks.
 
-## Q: Does video.js support video tracks?
+## Q: Does Video.js support video tracks?
 
-The code for video tracks exists but it has not been tested. See the [video tracks guide][video-tracks]
+Alternate video tracks support is in development. See [video tracks guide][video-tracks]
 for more information on using video tracks.
 
-## Q: Does video.js support text tracks (captions, subtitles, etc)?
+## Q: Does Video.js support text tracks (captions, subtitles, etc)?
 
 Yes! See the [text tracks guide][text-tracks] for information on using text tracks.
 
-## Q: Does video.js support HLS (HTTP Live streaming) video?
+## Q: Does Video.js support HLS (HTTP Live streaming) video?
 
-video.js supports HLS video if the native HTML5 element supports HLS (e.g. Safari, Edge,
-Chrome for Android, and iOS). For browsers without native support see the [videojs-contrib-hls][hls]
+Video.js supports HLS video if the native HTML5 element supports HLS (e.g. Safari, Edge,
+Chrome for Android, and iOS). For browsers without native support the [videojs-contrib-hls][hls]
 project which adds support.
 
-## Q: Does video.js support MPEG Dash video?
+Note that for non-native playback of HLS it is essential that the server hosting the video sets [CORS headers][cors].
 
-video.js itself does not support MPEG DASH, however an official project called [videojs-contrib-dash][dash]
-adds support for MPEG DASH video.
+## Q: Does Video.js support MPEG DASH video?
 
-## Q: Does video.js support live video?
+MPEG DASH support is provided byt the [videojs-contrib-dash][dash]
+package.
 
-Yes! Video.js adds support for live videos via the Flash tech tech which supports RTMP streams. In Video.js 6 you will have to use [videojs-flash][flash] to get this. In previous versions the Flash tech was builtin. The official HLS tech, [videojs-contrib-hls][hls], will add support for live HLS video
-if you add it to your page with video.js.
+Like HLS, DASH streams require [CORS headers][cors].
 
-## Q: Can video.js wrap around YouTube videos?
+## Q: Does Video.js support live video?
 
-No. There is an official plugin that adds support. It is called [videojs-youtube][youtube].
+Yes! Common formats for live are HLS or historically RTMP.
+HLS is supported via [videojs-contrib-hls][hls]. and RTMP via [videojs-flash][flash].
 
-## Q: Can video.js wrap around Vimeo videos?
+## Q: Can Video.js play YouTube videos?
 
-No. There is an official plugin that adds support. It is called [videojs-vimeo][vimeo].
+There is an official plugin that adds support, [videojs-youtube][youtube].
 
-## Q: Does video.js support DRM video?
+## Q: Can Video.js play Vimeo videos?
 
-No. There is an official plugin that adds support. It is called [videojs-contrib-eme][eme].
+There is an official plugin that adds support, [videojs-vimeo][vimeo].
 
-## Q: Does video.js have any support for advertisement integrations?
+## Q: Does Video.js support DRM video?
 
-No. There is an official plugin that adds support. It is called [videojs-contrib-ads][ads].
+There is an official plugin that adds support, [videojs-contrib-eme][eme].
 
-## Q: Can video.js be required in node.js?
+## Q: Does Video.js have any support for advertisement integrations?
 
-Yes! Please [submit an issue or open a pull request][pr-issue-question] if this does not work.
+There is an official plugin that adds core advertising support, [videojs-contrib-ads][ads]. Further plugins build on this which handle the communication with the ad server and display of the ad, for instance [Google's IMA plugin][google-ima].
 
-## Q: Does video.js work with webpack?
+## Q: Can Video.js be required in node.js?
 
-Yes! Please [submit an issue or open a pull request][pr-issue-question] if this does not work.
+Yes! Video.js is [published on NPM][node].
 
-We have a short guide that deals with small configurations that you will need to do. [Webpack and Videojs Configuration][webpack-guide].
+## Q: Does Video.js work with webpack?
 
-## Q: Does video.js work with react?
+Yes! See the [Webpack and Video.js configuration guide][webpack-guide].
+
+## Q: Does Video.js work with react?
 
 Yes! See [ReactJS integration example][react-guide].
 
@@ -282,6 +299,10 @@ Yes! See [ReactJS integration example][react-guide].
 
 [contributing-prs]: http://github.com/videojs/video.js/blob/master/CONTRIBUTING.md#contributing-code
 
+[components-guide]: /docs/guides/components.md
+
+[cors]: https://enable-cors.org
+
 [dash]: http://github.com/videojs/videojs-contrib-dash
 
 [debug-guide]: /docs/guides/debugging.md
@@ -292,12 +313,16 @@ Yes! See [ReactJS integration example][react-guide].
 
 [generator]: https://github.com/videojs/generator-videojs-plugin
 
+[google-ima]: https://github.com/googleads/videojs-ima
+
 [hls]: http://github.com/videojs/videojs-contrib-hls
 
 [install-guide]: http://videojs.com/getting-started/
 
 [issue-template]: http://github.com/videojs/video.js/blob/master/.github/ISSUE_TEMPLATE.md
 
+[node]: https://www.npmjs.com/package/video.js
+
 [npm-keywords]: https://docs.npmjs.com/files/package.json#keywords
 
 [plugin-guide]: /docs/guides/plugins.md
@@ -316,8 +341,12 @@ Yes! See [ReactJS integration example][react-guide].
 
 [skins-list]: https://github.com/videojs/video.js/wiki/Skins
 
+[slack]: https://videojs.slack.com
+
 [starter-example]: http://jsbin.com/axedog/edit?html,output
 
+[techorder]: [cors]: /docs/guides/options.md#techorder
+
 [text-tracks]: /docs/guides/text-tracks.md
 
 [troubleshooting]: /docs/guides/troubleshooting.md
diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md
index 912113663..ccad43012 100644
--- a/docs/guides/hooks.md
+++ b/docs/guides/hooks.md
@@ -1,6 +1,6 @@
 # Hooks
 
-Hooks exist so that users can "hook" on to certain video.js player lifecycle
+Hooks exist so that users can "hook" on to certain Video.js player lifecycle
 
 ## Table of Contents
 
@@ -20,21 +20,21 @@ Currently, the following hooks are avialable:
 
 `beforesetup` is called just before the player is created. This allows:
 
-* modification of the options passed to the video.js function (`videojs('some-id, options)`)
+* modification of the options passed to the Video.js function (`videojs('some-id, options)`)
 * modification of the dom video element that will be used for the player
 
 `beforesetup` hook functions should:
 
 * take two arguments
-  1. videoEl: dom video element that video.js is going to use to create a player
-  1. options: options that video.js was intialized with and will later pass to the player during creation
-* return options that will merge and override options that video.js with intialized with
+  1. videoEl: dom video element that Video.js is going to use to create a player
+  1. options: options that Video.js was intialized with and will later pass to the player during creation
+* return options that will merge and override options that Video.js with intialized with
 
 Example: adding beforesetup hook
 
 ```js
 var beforeSetup = function(videoEl, options) {
-  // videoEl.id will be some-id here, since that is what video.js
+  // videoEl.id will be some-id here, since that is what Video.js
   // was created with
 
   videoEl.className += ' some-super-class';
@@ -58,16 +58,16 @@ videojs('some-id', {autoplay: true, controls: true});
 
 `setup` is called just after the player is created. This allows:
 
-* plugin or custom functionalify to intialize on the player
+* plugin or custom functionality to intialize on the player
 * changes to the player object itself
 
 `setup` hook functions:
 
 * Take one argument
-  * player: the player that video.js created
+  * player: the player that Video.js created
 * Don't have to return anything
 
-Example: adding setup hook
+Example: adding a setup hook
 
 ```js
     var setup = function(player) {
@@ -76,7 +76,7 @@ Example: adding setup hook
     };
     var foo = function() {};
 
-    videojs.plugin('foo', foo);
+    videojs.registerPlugin('foo', foo);
     videojs.hook('setup', setup);
     var player = videojs('some-id', {autoplay: true, controls: true});
 ```
@@ -85,7 +85,7 @@ Example: adding setup hook
 
 ### Adding
 
-In order to use hooks you must first include video.js in the page or script that you are using. Then you add hooks using `videojs.hook(<name>, function)` before running the `videojs()` function.
+In order to use hooks you must first include Video.js in the page or script that you are using. Then you add hooks using `videojs.hook(<name>, function)` before running the `videojs()` function.
 
 Example: adding hooks
 
@@ -102,13 +102,13 @@ videojs.hook('setup', function(player) {
 var player = videojs('vid1', {autoplay: false});
 ```
 
-After adding your hooks they will automatically be run at the correct time in the video.js lifecycle.
+After adding your hooks they will automatically be run at the correct time in the Video.js lifecycle.
 
 ### Getting
 
-To access the array of hooks that currently exists and will be run on the video.js object you can use the `videojs.hooks` function.
+To access the array of hooks that currently exists and will be run on the Video.js object you can use the `videojs.hooks` function.
 
-Example: getting all hooks attached to video.js
+Example: getting all hooks attached to Video.js
 
 ```js
 var beforeSetupHooks = videojs.hooks('beforesetup');
@@ -117,7 +117,7 @@ var setupHooks = videojs.hooks('setup');
 
 ### Removing
 
-To stop hooks from being executed during the video.js lifecycle you will remove them using `videojs.removeHook`.
+To stop hooks from being executed during the Video.js lifecycle you will remove them using `videojs.removeHook`.
 
 Example: remove a hook that was defined by you
 
diff --git a/docs/guides/languages.md b/docs/guides/languages.md
index eef59df75..4ca1a1777 100644
--- a/docs/guides/languages.md
+++ b/docs/guides/languages.md
@@ -1,8 +1,9 @@
 # Languages
 
-Multiple language support allows for users of non-English locales to natively interact with the Video.js player.
+Video.js includes localization support to present text in a language other than the default English where appropriate.
 
-For an up-to-date list of the languages Video.js supports, see the [languages folder (`lang`)][lang-supported]. These JSON files are converted to JavaScript during the Video.js build process.
+For an up-to-date list of the languages Video.js supports, see the [languages folder (`lang`)][lang-supported].
+Some translations may be less complete than others - see the [translations needed doc][translations-needed] for a table of strings that are missing from the translations available.  Contributions are welcome to update those that are incomplete.
 
 ## Table of Contents
 
@@ -22,7 +23,9 @@ For an up-to-date list of the languages Video.js supports, see the [languages fo
 
 ## Using Video.js Languages
 
-Video.js ships with multiple translations (in `dist/lang/`) in JavaScript files. Each of these files can be included in a web page to provide support for that language in _all_ Video.js players:
+Video.js ships with multiple translations (in `dist/lang/`) in JavaScript files.
+Add the lang script for each language you need to support.
+Each of these files can be included in a web page to provide support for that language in _all_ Video.js players:
 
 ```html
 <script src="//example.com/path/to/video.min.js"></script>
@@ -31,7 +34,7 @@ Video.js ships with multiple translations (in `dist/lang/`) in JavaScript files.
 
 ## Contributing to Video.js Translations
 
-We welcome new translations and improvements to existing ones! Please see the [contributing document](../../CONTRIBUTING.md) to get started contributing to Video.js and continue reading for specifics on how to contribute to translations of Video.js...
+We welcome new translations and improvements to existing ones! Please see the [contributing document](../../CONTRIBUTING.md) to get started contributing to Video.js and continue reading for specifics on how to contribute to translations of Video.js.
 
 ### JSON Format
 
@@ -50,11 +53,9 @@ Video.js uses a JSON object to describe a language, where the keys are English a
 
 ### File Naming
 
-Translations are always found in the `lang/` directory.
+Translations are found in the `lang/` directory.
 
-Each file's name should be the [standard language code][lang-codes] that is most appropriate. For example, "es" for Spanish or "zh-CN" for Chinese.
-
-Finally, each file's extension is always `.json`.
+Each file's name should be the [standard language code][lang-codes] that is most appropriate, with a `.json` extension. For example, "es.json" for Spanish or "zh-CN.json" for simplified Chinese.
 
 ### Updating an Existing Translation
 
@@ -80,20 +81,14 @@ cp lang/en.json lang/${NEW_LANG_CODE}.json
 
 Otherwise, the process is the same as [updating an existing translation](#updating-an-existing-translation).
 
-## Advanced Language Usage
-
-The instructions above for [using Video.js languages](#using-videojs-languages) should be sufficient for the majority of use-cases. However, languages can be provided at runtime.
-
-In each case, these custom language definitions _take precedence over any Video.js-provided languages!_
-
 ### Adding Languages via the API
 
 In addition to the stand-alone scripts provided by Video.js, the API supports manual definition of new languages via the `addLanguage` method. It takes two arguments: the [standard language code][lang-codes] and a [language definition object](#json-format).
 
 ```js
 videojs.addLanguage('es', {
-  'Play': 'Reproducción',
-  'Pause': 'Pausa',
+  Play: 'Reproducción',
+  Pause: 'Pausa',
   'Current Time': 'Tiempo reproducido',
   'Duration Time': 'Duración total',
   'Remaining Time': 'Tiempo restante',
@@ -101,7 +96,9 @@ videojs.addLanguage('es', {
 });
 ```
 
-### Per-Player Languages
+`addLanguage()` will overwrite existing translations if the object includes strings previously translated. However text that has already been localised will not be updated after generation.
+
+### Per-Player Translations
 
 In addition to providing languages to Video.js itself, individual `Player` instances can be provided custom language support via [the `languages` option](/docs/guides/options.md#languages):
 
@@ -109,31 +106,34 @@ In addition to providing languages to Video.js itself, individual `Player` insta
 // Provide a custom definition of Spanish to this player.
 videojs('my-player', {
   languages: {
-    es: {...}
+    es: {
+      Play: 'Reproducir'
+    }
   }
 });
 ```
 
-### Setting Default Player Language
+### Setting Player Language
 
-Player instances can also have a default language via [the `language` option](/docs/guides/options.md#language):
+The language used by a player instance may be set via [the `language` option](/docs/guides/options.md#language):
 
 ```js
-// Set the default language to Spanish for this player.
+// Set the language to Spanish for this player.
 videojs('my-player', {
   language: 'es'
 });
 ```
 
-Additionally, the `language` method of the player can be used to set the language after instantiation (e.g., `language('es')`). However, this is not recommended as it does not update the UI in place. _Setting the language via options is always preferred._
+The `language` method of the player _can_ be used to set the language after instantiation with `language('es')`. However, this is generally not useful as it does not update text that is already in place.
 
 ### Determining Player Language
 
 The player language is set to one of the following in descending priority:
 
 * The language [specified in options](#setting-default-player-language)
-* The language specified by the closest element with a `lang` attribute. This could be the player itself or a parent element. Usually, the document language is specified on the `<html>` tag.
-* Browser language preference; the first language if more than one is configured
+* The language specified by a `lang` attribute on the player element.
+* The language specified by the closest parent element with a `lang` attribute, up to and including the `<html>` element.
+* The browser language preference; the first language if more than one is configured
 * English
 
 #### Internal Language Selection
@@ -147,10 +147,12 @@ For information on translation/localization in plugins, see [the plugins guide](
 
 Standard languages codes [are defined by the IANA][lang-codes].
 
-For all existing/supported languages, please see the [languages lolder (`lang/`)][lang-supported] folder located in the project root.
+For all existing/supported languages, please see the [languages folder (`lang/`)][lang-supported] folder located in the project root.
 
 [lang-en]: /lang/en.json
 
 [lang-supported]: /lang
 
 [lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
+
+[translations-needed]: https://github.com/videojs/video.js/blob/master/docs/translations-needed.md
diff --git a/docs/guides/options.md b/docs/guides/options.md
index 0815f6cdb..7132cad75 100644
--- a/docs/guides/options.md
+++ b/docs/guides/options.md
@@ -36,8 +36,13 @@
   * [${componentName}](#componentname)
 * [Tech Options](#tech-options)
   * [${techName}](#techname)
+  * [flash](#flash)
+    * [swf](#swf)
+  * [html5](#html5)
     * [nativeControlsForTouch](#nativecontrolsfortouch-1)
+    * [nativeAudioTracks](#nativeaudiotracks)
     * [nativeTextTracks](#nativetexttracks)
+    * [nativeVideoTracks](#nativevideotracks)
 
 ## Standard `<video>` Element Options
 
@@ -203,49 +208,6 @@ Although, since the `plugins` option is an object, the order of initialization i
 
 See [the plugins guide][plugins] for more information on Video.js plugins.
 
-### `sourceOrder`
-
-> Type: `boolean`, Default: `false`
->
-> **Note:** In video.js 6.0, this option will default to `true`. and that [videojs-flash](https://github.com/videojs/videojs-flash) will be required to use the flash tech.
-
-Tells Video.js to prefer the order of [`sources`](#sources) over [`techOrder`](#techorder) in selecting a source and playback tech.
-
-Given the following example:
-
-```js
-videojs('my-player', {
-  sourceOrder: true,
-  sources: [{
-    src: '//path/to/video.flv',
-    type: 'video/x-flv'
-  }, {
-    src: '//path/to/video.mp4',
-    type: 'video/mp4'
-  }, {
-    src: '//path/to/video.webm',
-    type: 'video/webm'
-  }],
-  techOrder: ['html5', 'flash']
-});
-```
-
-Normally, the fact that HTML5 comes before Flash in the `techOrder` would mean Video.js would look for a compatible _source_ for HTML5 and would pick either the MP4 or WebM video (depending on browser support) only falling back to Flash if no compatible source for HTML5 was found.
-
-However, because the `sourceOrder` is `true`, Video.js flips that process around. It will look for a compatible _tech_ for each source in order. Presumably, it would first find a match between the FLV (since it's first in the source order) and the Flash tech.
-
-In summary, the default algorithm is:
-
-* for each tech:
-  * for each source:
-    * if tech can play source, use this tech/source combo
-
-With `sourceOrder: true`, the algorithm becomes:
-
-* for each source:
-  * for each tech:
-    * if tech can play source, use this tech/source combo
-
 ### `sources`
 
 > Type: `Array`
@@ -285,7 +247,7 @@ Defines the order in which Video.js techs are preferred. By default, this means
 
 Allows overriding the default URL to vtt.js, which may be loaded asynchronously to polyfill support for `WebVTT`.
 
-This option will be used in the "novtt" build of video.js (i.e. `video.novtt.js`). Otherwise, vtt.js is bundled with video.js.
+This option will be used in the "novtt" build of Video.js (i.e. `video.novtt.js`). Otherwise, vtt.js is bundled with Video.js.
 
 ## Component Options
 
@@ -346,7 +308,11 @@ videojs('my-player', {
 
 Video.js playback technologies (i.e. "techs") can be given custom options as part of the options passed to the `videojs` function. They should be passed under the _lower-case variant of the tech name_ (e.g. `"flash"` or `"html5"`).
 
-This is not used in most implementations, but one case where it may be is dictating where the Video.js SWF file is located for the `Flash` tech:
+### `flash`
+
+#### `swf`
+
+Specifies where the Video.js SWF file is located for the `Flash` tech:
 
 ```js
 videojs('my-player', {
@@ -356,24 +322,38 @@ videojs('my-player', {
 });
 ```
 
-However, this is a case where changing the global defaults is more useful:
+However, changing the global defaults is generally more appropriate:
 
 ```js
 videojs.options.flash.swf = '//path/to/videojs.swf'
 ```
 
+### `html5`
+
 #### `nativeControlsForTouch`
 
 > Type: `boolean`
 
 Only supported by the `Html5` tech, this option can be set to `true` to force native controls for touch devices.
 
+#### `nativeAudioTracks`
+
+> Type: `boolean`
+
+Can be set to `false` to disable native audio track support. Most commonly used with [videojs-contrib-hls][videojs-contrib-hls].
+
 #### `nativeTextTracks`
 
 > Type: `boolean`
 
 Can be set to `false` to force emulation of text tracks instead of native support. The `nativeCaptions` option also exists, but is simply an alias to `nativeTextTracks`.
 
+#### `nativeVideoTracks`
+
+> Type: `boolean`
+
+Can be set to `false` to disable native video track support. Most commonly used with [videojs-contrib-hls][videojs-contrib-hls].
+
 [plugins]: /docs/guides/plugins.md
 
 [languages]: /docs/guides/languages.md
@@ -383,3 +363,5 @@ Can be set to `false` to force emulation of text tracks instead of native suppor
 [lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
 
 [video-attrs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#Attributes
+
+[videojs-contrib-hls]: https://github.com/videojs/videojs-contrib-hls
diff --git a/docs/guides/player-workflows.md b/docs/guides/player-workflows.md
index d383ac3fe..5f94068cf 100644
--- a/docs/guides/player-workflows.md
+++ b/docs/guides/player-workflows.md
@@ -99,7 +99,7 @@ Example
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   // get
   var howLoudIsIt = myPlayer.volume();
@@ -113,7 +113,7 @@ Volume can also be muted (without actually changing the volume value) using the
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   // get, should be false
   console.log(myPlayer.muted());
@@ -131,7 +131,7 @@ To check if the player is currently fullscreen call the `isFullscreen` function
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   // get, should be false
   console.log(myPlayer.isFullscreen());
@@ -149,7 +149,7 @@ To request that the player enter fullscreen call `requestFullscreen`.
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   myPlayer.requestFullscreen();
 });
@@ -160,7 +160,7 @@ To exit fullscreen call `exitFullscreen`
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   myPlayer.requestFullscreen();
   myPlayer.exitFullscreen();
@@ -174,7 +174,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   myPlayer.play();
 });
@@ -185,7 +185,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   myPlayer.play();
   myPlayer.pause();
@@ -197,7 +197,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 
 myPlayer.ready(function() {
   // true
@@ -224,7 +224,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   // set current time to 2 minutes into the video
   myPlayer.currentTime(120);
@@ -239,7 +239,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   var lengthOfVideo = myPlayer.duration();
 });
@@ -249,7 +249,7 @@ myPlayer.ready(function() {
 
 ```js
 var myPlayer = videojs('some-player-id');
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
    myPlayer.currentTime(10);
 
@@ -263,7 +263,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   var bufferedTimeRange = myPlayer.buffered();
 
@@ -288,7 +288,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
   // example 0.11 aka 11%
   var howMuchIsDownloaded = myPlayer.bufferedPercent();
@@ -302,7 +302,7 @@ Passing a source to the player via the API. (this can also be done using options
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 ```
 
 **Source Object (or element):** A javascript object containing information
@@ -351,10 +351,9 @@ function on the player.
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src("http://www.example.com/path/to/video.mp4");
+myPlayer.src('http://www.example.com/path/to/video.mp4');
 myPlayer.ready(function() {
-   // function call throws an error if we
-    // dont add {IWillNotUseThisInPlugins: true}
+   // tech() will error with no argument
    var tech = myPlayer.tech({IWillNotUseThisInPlugins: true});
 });
 ```
diff --git a/docs/guides/plugins.md b/docs/guides/plugins.md
index 2ff0d4eba..52ef0d9e2 100644
--- a/docs/guides/plugins.md
+++ b/docs/guides/plugins.md
@@ -10,14 +10,6 @@ Because we view plugins as such an important part of Video.js, the organization
 
   In short, the generator sets up plugin authors to focus on writing their plugin - not messing with tools.
 
-* [videojs-spellbook][spellbook]
-
-  As of version 3, the plugin generator includes a new dependency: [videojs-spellbook][spellbook]. Spellbook is a kitchen sink plugin development tool: it builds plugins, creates tags, runs a development server, and more.
-
-  The benefit of Spellbook is that you can run the generator _once_ and receive updates and bugfixes in Spellbook without having to run the generator again and deal with Yeoman conflicts and other headaches.
-
-  As long as your plugin project follows the [conventions][standards], Spellbook should work on it!
-
 ## Writing a Basic Plugin
 
 If you've written a Video.js plugin before, the basic plugin concept should be familiar. It's similar to a jQuery plugin in that the core idea is that you're adding a method to the player.
@@ -57,7 +49,7 @@ After that, any player will automatically have an `examplePlugin` method on its
 
 ## Writing an Advanced Plugin
 
-Video.js 6 introduces advanced plugins: these are plugins that share a similar API with basic plugins, but are class-based and offer a range of extra features out of the box.
+Video.js 6 introduced advanced plugins: these are plugins that share a similar API with basic plugins, but are class-based and offer a range of extra features out of the box.
 
 While reading the following sections, you may want to refer to the [Plugin API docs][api-plugin] for more detail.
 
@@ -109,7 +101,7 @@ var ExamplePlugin = videojs.extend(Plugin, {
 
 For now, this example advanced plugin does the exact same thing as the basic plugin described above - not to worry, we will make it more interesting as we continue!
 
-### Register a Advanced Plugin
+### Register an Advanced Plugin
 
 The registration process for advanced plugins is identical to [the process for basic plugins](#register-a-basic-plugin).
 
diff --git a/docs/guides/react.md b/docs/guides/react.md
index 76146b5d2..2d3702fd7 100644
--- a/docs/guides/react.md
+++ b/docs/guides/react.md
@@ -1,8 +1,8 @@
-# video.js and ReactJS integration
+# Video.js and ReactJS integration
 
 Here's a basic ReactJS player implementation.
 
-It just instantiates the video.js player on `componentDidMount` and destroys it on `componentWillUnmount`.
+It just instantiates the Video.js player on `componentDidMount` and destroys it on `componentWillUnmount`.
 
 ```jsx
 import React from 'react';
@@ -10,7 +10,7 @@ import videojs from 'video.js'
 
 export default class VideoPlayer extends React.Component {
   componentDidMount() {
-    // instantiate video.js
+    // instantiate Video.js
     this.player = videojs(this.videoNode, this.props, function onPlayerReady() {
       console.log('onPlayerReady', this)
     });
@@ -51,7 +51,7 @@ const videoJsOptions = {
 return <VideoPlayer { ...videoJsOptions } />
 ```
 
-Dont forget to include the video.js CSS, located at `video.js/dist/video-js.css`.
+Don't forget to include the Video.js CSS, located at `video.js/dist/video-js.css`.
 
 [options]: /docs/guides/options.md
 
@@ -132,7 +132,7 @@ export default vjsEpisodeList;
 
 // ...
   componentDidMount() {
-    // instantiate video.js
+    // instantiate Video.js
     this.player = videojs(this.videoNode, this.props, function onPlayerReady() {
       console.log('onPlayerReady', this)
     });
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 4e42601ac..c1eed0f27 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -96,6 +96,8 @@ Alternatively, you can use the `data-setup` attribute to pass options as [JSON][
 <video data-setup='{"controls": true, "autoplay": false, "preload": "auto"}'...>
 ```
 
+> **Note:** You _must_ use single-quotes around the value of `data-setup` as it contains a JSON string which must use double quotes.
+
 Finally, if you're not using the `data-setup` attribute to trigger the player setup, you can pass in an object of player options as the second argument to the `videojs` function:
 
 ```js
@@ -106,6 +108,8 @@ videojs('my-player', {
 });
 ```
 
+> **Note:** Do not use both `data-setup` and an options object.
+
 ### Global Defaults
 
 Default options for all players can be found at `videojs.options` and can be changed directly. For example, to set `{autoplay: true}` for all future players:
@@ -171,7 +175,9 @@ player.on('ready', function() {
 });
 ```
 
-In each case, the callback is called asynchronously - _even if the player is already ready!_
+In each case, the callback is called asynchronously.
+
+An important distinction between the above methods is that adding an listener for `ready` with `on()` _must_ be done before the player is ready. With `player.ready()`, the function is called immediately if the player is already ready.
 
 ## Advanced Player Workflows
 
diff --git a/docs/guides/tech.md b/docs/guides/tech.md
index fc69af49e..89b4af699 100644
--- a/docs/guides/tech.md
+++ b/docs/guides/tech.md
@@ -1,12 +1,14 @@
 # Playback Technology ("Tech")
 
-Playback Technology refers to the specific browser or plugin technology used to play the video or audio. When using HTML5, the playback technology is the video or audio element. When using Flash, the playback technology is the specific Flash player used, e.g. Flowplayer, YouTube Player, video-js.swf, etc. (not just "Flash"). This could also include Silverlight, Quicktime, or any other plugin that will play back video in the browser, as long as there is an API wrapper written for it.
+Playback Technology refers to the specific browser or plugin technology used to play the video or audio. When using HTML5, the playback technology is the video or audio element. When using Flash from [videojs-flash][flash], the playback technology is the video-js.swf Flash object. When using the [videojs-youtube][youtube] tech, the playback technology is the You Tube player. The tech also includes an API wrapper to translate between the Video.js controls and API to the specific playback technology used.
 
-Essentially we're using HTML5 and plugins only as video decoders, and using HTML and JavaScript to create a consistent API and skinning experience across all of them.
+Essentially we're using html5 and plugins only as video decoders, and using HTML and JavaScript to create a consistent API and skinning experience across all of them.
+
+In addition to techs there are source handlers. Source handlers add the capability to play additional source types to techs. For example, the [videojs-contrib-hls][hls] source handler enables the HTML5 and Flash techs to play HLS.
 
 ## Building an API Wrapper
 
-We'll write a more complete guide on writing a wrapper soon, but for now the best resource is the [Video.js](https://github.com/zencoder/video-js/tree/master/src) source where you can see how both the HTML5 and video-js.swf API wrappers were created.
+We'll write a more complete guide on writing a wrapper soon, but for now the best resource is the [Video.js](https://github.com/videojs/video.js/tree/master/src/js/tech) source where you can see how the HTML5 API wrapper is created.
 
 ## Required Methods
 
@@ -39,7 +41,7 @@ exitFullScreen
 
 ## Adding Playback Technology
 
-When adding additional Tech to a video player, make sure to add the supported tech to the video object.
+When additional techs are added they are automatically added to the `techOrder`. You can modify the `techOrder` to change the priority of each tech.
 
 ### Tag Method:
 
@@ -57,47 +59,58 @@ videojs("videoID", {
 
 ## Technology Ordering
 
-By default Video.js performs "Tech-first" ordering when it searches for a source/tech combination to play videos. This means that if you have two sources and two techs, video.js will try to play each video with the first tech in the `techOrder` option property before moving on to try the next playback technology.
+When Video.js is given an array of sources, which to use is determined by finding the first supported source / tech combination. Each tech will be queried in the order specified in `techOrder` whether it can play the first source. The first match wins. If no tech can play the first source, then the next will be tested. It's important to set the `type` of each source correctly for this test to be accurate.
 
-Tech-first ordering can present a problem if you have a `sourceHandler` that supports both `Html5` and `Flash` techs such as videojs-contrib-hls.
-
-For example, given the following video element:
+For example, given the following video element, assuming the [videojs-flash][flash] tech and [videojs-contrib-hls][hls] source handler are available:
 
 ```html
-<video data-setup='{"techOrder": ["html5", "flash"]}'>
+<!-- "techOrder": ["html5", "flash"] -->
+<video
   <source src="http://your.static.provider.net/path/to/video.m3u8" type="application/x-mpegURL">
   <source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
 </video>
 ```
 
-There is a good chance that the mp4 source will be selected on platforms that do not have media source extensions. Video.js will try all sources against the first playback technology, in this case `Html5`, and select the first source that can play - in this case MP4.
+The HLS source will be tested first. The first tech is html5.
+* Safari can play HLS in a standard HTML5 video element, so HLS will be played using the html5 tech
+* Chrome can't play HLS in the standard HTML5 video element on its own, but the videojs-contrib-hls source handler _can_ play HLS via [Media Source Extensions][mse] in HTML5. So HLS will be played in the html5 tech
+* IE 10 can't play HLS natively, and doesn't support Media Source Extensions. As the source cannot be played in HTML5, the Flash tech can be tested. The videojs-contrib-hls source handler can play HLS in the Flash tech, so HLS will be played in the Flash tech.
 
-In "Tech-first" mode, the tests run something like this:
-  Can video.m3u8 play with Html5? No...
-  Can video.mp4 play with Html5? Yes! Use the second source.
-
-Video.js now provides another method of selecting the source - "Source-first" ordering. In this mode, Video.js tries the first source against every tech in `techOrder` before moving onto the next source.
-
-With a player setup as follows:
+Now take the same sources again with videojs-contrib-hls but without videojs-flash:
 
 ```html
-<video data-setup='{"techOrder": ["html5", "flash"], "sourceOrder": true}'>
+<!-- "techOrder": ["html5"] -->
+<video
   <source src="http://your.static.provider.net/path/to/video.m3u8" type="application/x-mpegURL">
   <source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
 </video>
 ```
 
-The Flash-based HLS support will be tried before falling back to the MP4 source.
+* Safari will play HLS in the html5 tech
+* Chrome will play HLS in the html5 tech by means of videojs-contrib-hls
+* IE 10 can't play HLS in either the html5 or Flash tech. Next the MP4 source will be tested. MP4 can be played by HTML5, so that source-tech pair will be used.
 
-In "Source-first" mode, the tests run something like this:
-  Can video.m3u8 play with Html5? No...
-  Can video.m3u8 play with Flash? Yes! Use the first source.
+This time, we have videojs-flash but not videojs-contrib-hls:
+
+```html
+<!-- "techOrder": ["html5", "flash"] -->
+<video
+  <source src="http://your.static.provider.net/path/to/video.m3u8" type="application/x-mpegURL">
+  <source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
+</video>
+```
+
+* Safari will play HLS in the html5 tech
+* Chrome can't play HLS in the html5 or flash tech, so will play MP4 in the html5 tech.
+* IE 10 also can't play HLS in either the html5 or Flash tech and will also play MP4 in the html5 tech.
 
 ## Flash Technology
 
-The Flash playback tech is a part of the default `techOrder`. You may notice undesirable playback behavior in browsers that are subject to using this playback tech, in particular when scrubbing and seeking within a video. This behavior is a result of Flash's progressive video playback.
+The Flash playback tech was previously included in Video.js core and was included in the default `techOrder`. As of version 6, the Flash tech was moved to a separate [videojs-flash plugin][flash] which you would need to include if you still need to use Flash.
 
-### Enabling Streaming Playback
+It's increasingly likely that end users don't have Flash or their browser has either disabled it or puts a click-to-play or other barrier to using it, so it's strongly recommended to use an alternative such as HLS.
+
+### Enabling RTMP Streaming Playback
 
 In order to force the Flash tech to choose streaming playback, you need to provide a valid streaming source **before other valid Flash video sources**. This is necessary because of the source selection algorithm, where playback tech chooses the first possible source object with a valid type. Valid streaming `type` values include `rtmp/mp4` and `rtmp/flv`. The streaming `src` value requires valid connection and stream strings, separated by an `&`. An example of supplying a streaming source through your HTML markup might look like:
 
@@ -118,3 +131,13 @@ All four RTMP protocols are valid in the `src` (RTMP, RTMPT, RTMPE, and RTMPS).
 #### A note on sandboxing and security
 
 In some environments, such as Electron and NW.js apps, stricter policies are enforced, and `.swf` files won’t be able to communicate with the outside world out of the box. To stream media, you have to add them to a special manifest of trusted files. [nw-flash-trust](https://github.com/szwacz/nw-flash-trust) makes this job easy.
+
+Browsers also prevent the Flash tech from working when you load a page from the filesystem (with the `file:` protocol) and also in sandboxed iframes.
+
+[flash]: https://github.com/videojs/videojs-flash
+
+[hls]: https://github.com/videojs/videojs-contrib-hls
+
+[mse]: https://en.wikipedia.org/wiki/Media_Source_Extensions
+
+[youtube]: https://github.com/videojs/videojs-youtube
diff --git a/docs/guides/videojs.md b/docs/guides/videojs.md
index ba640ad88..dccf02866 100644
--- a/docs/guides/videojs.md
+++ b/docs/guides/videojs.md
@@ -11,7 +11,7 @@
 * [extend()](#extend)
 * [mergeOptions()](#mergeoptions)
 * [bind()](#bind)
-* [plugin()](#plugin)
+* [registerPlugin()](#plugin)
 * [xhr()](#xhr)
 
 ## `videojs()`
@@ -126,13 +126,13 @@ videojs.bind(someObj, function() {
 });
 ```
 
-## `plugin()`
+## `registerPlugin()`
 
 **See the [plugin guide](/docs/guides/plugins.md) in the docs for a more detailed example**
 
 ```js
 // Make a plugin that alerts when the player plays
-videojs.plugin('myPlugin', function(myPluginOptions) {
+videojs.registerPlugin('myPlugin', function(myPluginOptions) {
   myPluginOptions = myPluginOptions || {};
 
   var player = this;
diff --git a/docs/guides/webpack.md b/docs/guides/webpack.md
index 302fc6145..130d5eecd 100644
--- a/docs/guides/webpack.md
+++ b/docs/guides/webpack.md
@@ -1,6 +1,6 @@
 # Using Webpack with Video.js
 
-video.js, and the playback technologies such as videojs-contrib-hls all work in a Webpack based build environment. Here are several configuration changes specific to Webpack that will get you up and running.
+Video.js, and the playback technologies such as videojs-contrib-hls all work in a Webpack based build environment. Here are several configuration changes specific to Webpack that will get you up and running.
 
 ## Video.js CSS:
 To add the CSS that the player requires, simply add
diff --git a/docs/index.md b/docs/index.md
index 55e58f273..88694f925 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -28,11 +28,11 @@ Guides explain general topics and use cases (e.g. setup). API docs are automatic
 
 ### [FAQ](/docs/guides/faq.md)
 
-The frequently asked questions for video.js.
+The frequently asked questions for Video.js.
 
 ### [Troubleshooting](/docs/guides/troubleshooting.md)
 
-Troubleshooting help for video.js.
+Troubleshooting help for Video.js.
 
 ## [Guides](/docs/guides/)
 
@@ -58,7 +58,7 @@ Tracks are used for displaying text information over a video, selecting differen
 
 #### [Skins](/docs/guides/skins.md)
 
-You can change the look of the player across playback technologies just by editing a CSS file. The skins documentation gives you a intro to how the HTML and CSS of the default skin is put together. For a list of skins you can check the [video.js wiki][skins-list].
+You can change the look of the player across playback technologies just by editing a CSS file. The skins documentation gives you a intro to how the HTML and CSS of the default skin is put together. For a list of skins you can check the [Video.js wiki][skins-list].
 
 #### [Plugins](/docs/guides/plugins.md)