From ca51f5ca88f6dfaa7530691548608ebdce4fbcbb Mon Sep 17 00:00:00 2001
From: AJ ONeal <coolaj86@gmail.com>
Date: Tue, 3 Dec 2013 01:37:35 -0600
Subject: [PATCH] updated README

---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/README.md b/README.md
index 4b27590..35a0ac2 100644
--- a/README.md
+++ b/README.md
@@ -2,3 +2,69 @@ knuth-shuffle
 =============
 
 The Fisher-Yates (aka Knuth) shuffle for Browser and Node.js
+
+The Fisher-Yates (Knuth) Shuffle
+===
+
+As Microsoft learned the hard way (see article below), `function random() { return 0.5 - Math.random() }` turns out to be no-so-random at all.
+
+The fisher-yates shuffle is an algorithm so simple that not even
+[IEEE floating point math](http://blogs.adobe.com/bparadie/2011/11/22/0-2-0-1-0-30000000000000004/)
+can screw it up!
+
+I put this on npm as `knuth-shuffle` because `fisher-yates-shuffle`
+was just too long of a name and shuffle was already taken.
+
+Browser Example
+===
+
+```html
+<script src="./knuth-shuffle.js"></script>
+```
+
+```javascript
+(function () {
+  'use strict';
+
+  var a = [2,11,37,42]
+    , b
+    ;
+
+  // The shuffle modifies the original array
+  // calling a.slice(0) creates a copy, which is assigned to b
+  b = window.knuthShuffle(a.slice(0));
+  console.log();
+});
+```
+
+Node Example
+===
+
+```bash
+npm install -S knuth-shuffle
+```
+
+```javascript
+(function () {
+  'use strict';
+
+  var shuffle = require('knuth-shuffle').knuthShuffle
+    , a = [2,11,37,42]
+    , b
+    ;
+
+  // The shuffle modifies the original array
+  // calling a.slice(0) creates a copy, which is assigned to b
+  b = shuffle(a.slice(0));
+  console.log();
+});
+```
+
+See Also
+===
+
+  * [Mike Bostock's Fisher–Yates Shuffle Visualization](http://bost.ocks.org/mike/shuffle/)
+  * [How to randomize/shuffle a JavaScript array](http://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array)
+  * [Fisher-Yates Shuffle on Wikipedia](http://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle)
+  * [Doing the Microsoft Shuffle: Algorithm Fail in Browser Ballot](http://www.robweir.com/blog/2010/02/microsoft-random-browser-ballot.html)
+  * [knuth-shuffle on NPM](https://npmjs.org/package/citare-scriptum)