@brycefisher Added a guide on player disposal. closes videojs#1803

CHANGELOG.md

@@ -9,8 +9,8 @@ CHANGELOG
 * @Sxmanek added a Czech translation ([view](/~https://github.com/videojs/video.js/pull/1739))
 * @jcaron23 added the vjs-scrubbing CSS class and prevented menus from showing while scrubbing ([view](/~https://github.com/videojs/video.js/pull/1741))
 * @dmlap fixed URL parsing in IE9 ([view](/~https://github.com/videojs/video.js/pull/1765))
-* Fixed issue where ManualTimeUpdatesOff was not de-registering events ([view](/~https://github.com/videojs/video.js/pull/1793))
-
+* @gkatsev Fixed issue where ManualTimeUpdatesOff was not de-registering events ([view](/~https://github.com/videojs/video.js/pull/1793))
+* @brycefisher Added a guide on player disposal ([view](/~https://github.com/videojs/video.js/pull/1803))
 --------------------
 
 ## 4.11.3 (2014-12-19)
@@ -43,7 +43,7 @@ CHANGELOG
 * @mmcc fixed localization of captions/subtitles menu off buttons ([view](/~https://github.com/videojs/video.js/pull/1632))
 
 ## 4.10.1 (2014-10-29)
-@heff removed his own stupid error ([view])(/~https://github.com/videojs/video.js/commit/a12dd770572a7f16e436e2332eba7ffbb1f1b9b9)
+@heff removed his own stupid error [view](/~https://github.com/videojs/video.js/commit/a12dd770572a7f16e436e2332eba7ffbb1f1b9b9)
 
 ## 4.10.0 (2014-10-28)
 * @aptx4869 fixed an issue where the native JSON parser wasn't used ([view](/~https://github.com/videojs/video.js/pull/1565))

docs/guides/removing-players.md

@@ -0,0 +1,41 @@
+Removing Players
+================
+
+Sometimes, you want to remove players after page load (in single page apps or modals, for instance). It's easy to manage, but there are some simple rules you need to follow.
+
+Call `.dispose()`
+-----------------
+
+To remove the html associated with your videojs player from the page always call the player's [`dispose()`](/~https://github.com/videojs/video.js/blob/stable/docs/api/vjs.Player.md#dispose) method:
+
+```javascript```
+var oldPlayer = document.getElementById('my-player');
+videojs(oldPlayer).dispose(); 
+```
+
+This method will:
+
+  1. reset the internal state of videojs
+  2. remove the player's dom from the page
+
+Showing / Hiding a Player
+-------------------------
+
+For instance, if you have a modal that a player appears in, you should create the player when the modal pops up. When the modal hides, dispose the player. If you try to hide the Flash tech, things will go poorly. Even with other tech, calling `dispose()` on a player that's not needed will free up resources for the browser.
+
+Why Is This Needed?
+-------------------
+
+VideoJS internally tracks all players and their associated data by html id attribute. If you plan to create new players with the same id as previously created players, you'll need to call the player's dispose() method to clear VideoJS's internal state before creating the new player.
+
+Signs You Did It Wrong
+-------------------------
+
+```
+TypeError: this.el_.vjs_getProperty is not a function
+"VIDEOJS:" "Video.js: buffered unavailable on Hls playback technology element." TypeError: this.el_.vjs_getProperty is not a function
+Stack trace:
+...
+```
+
+If you encounter a console error in the browser similar to the above, you've probably forgotten to `dispose()` a player before removing it from the dom. This would happen when using the [contrib-hls](/~https://github.com/videojs/videojs-contrib-hls) plugin.

docs/index.md

@@ -30,6 +30,8 @@ There are two categories of docs: [Guides](./guides/) and [API docs](./api/). Gu
 
 * [Glossary](./guides/glossary.md) - Some helpful definitions.
 
+* [Removing Players](./guides/removing-players.md) - Helpful for using VideoJS in single page apps.
+
 ## API Docs
 - The most relevant API doc is the [player API doc](./api/vjs.Player.md).
 - [Full list of API Docs](./api/)