Merge pull request #5 from kagemusha/master

Update README.md

README.md

@@ -1,23 +1,32 @@
 # ember-cli-deploy-manifest
 
-This plugin generates a text manifest of all built assets that can be used by other plugins to perform a differential (i.e. speedier) upload.
+This plugin generates a [manifest file](https://en.wikipedia.org/wiki/Manifest_file) listing the versioned asset files generated by your app's build process.  By comparing the latest manifest to the previous one, your deployment plugin (such as [ember-cli-deploy-s3](https://github.com/zapnito/ember-cli-deploy-s3)) can determine which files have changed and only upload those, improving efficiency.
 
-How does this work in practice? As an example, the [ember-cli-deploy-s3](https://github.com/zapnito/ember-cli-deploy-s3) plugin will upload this manifest to its bucket and, when asked to upload a set of assets, will download the most recent manifest to quickly compare against the new manifest to determine which files actually need uploading. This is possible because we are using content-based fingerprints in the filenames, so if there is a matching filename, we can assume that we do not need to re-upload the file.
+**How does this work in detail?**
 
-## Example
+When you build your ember-cli app in development, your files get globbed together into a bunch of asset files such as myapp.js vendor.js, myapp.css, and vendor.css (see your project's dist/assets dir).
 
-In deployment #1, we build our app and generate 4 files:
+When you do a production build, your build process will produce fingerprinted copies of these asset files.  Fingerprints are used for versioning as described [here](https://en.wikipedia.org/wiki/Fingerprint_(computing)).  In practice fingerprints are long hash strings, but for exposition we'll pretend our fingerprints look like a version number.  So our manifest will look like:
 
 ```
-app-abc123.js
-vendor-def456.js
-app-ghi789.css
-vendor-jkl012.css
+myapp-1.js
+vendor-1.js
+myapp-1.css
+vendor-1.css
 ```
 
-This plugin generates this list as `manifest.txt` and the s3 plugin (or another plugin with similar intent) uploads the manifest file to S3 along with all 4 asset files.
+The first time we deploy, our deployment plugin uploads everything, including our manifest file.
 
-A few minutes pass, and you make a change to a javascript file in your app. You kick off deployment #2, and the build step generates 4 files, of which only the `app-*.js` file has changed. This time, the s3 plugin downloads the previous manifest from the s3 bucket, compares it to the new one, and notices that the only difference is the `app-*.js` file, so it only uploads that file, which is much faster than uploading all of the files.
+Say we then edit our app javascript but everything else remains the same.  After rebuilding, when we generate our new manifest, it will look something like:
+
+```
+myapp-2.js
+vendor-1.js
+myapp-1.css
+vendor-1.css
+```
+
+When our deployment plugin is ready to deploy, it retrieves the old manifest (from S3 or wherever its stored), diffs it with the current one, and determines it only has to upload myapp-2.js.  For large asset files, this can save alot of time and bandwidth.
 
 ## Installation