docs(aio): add zipper documentation (#18151)

PR Close #18151

aio/tools/example-zipper/README.md

@@ -1,4 +1,73 @@
 # Overview
 
-In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project
+In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project packaged as a zip file. These zip files are generated by the utility in this folder.
-packaged as a zip file. These zip files are generated by the utility in this folder.
+
+## Example zipper
+
+The  `exampleZipper.js` tool is very similar to the Plunker's `builder.js`. The latter creates an HTML file with all the examples' files and the former creates a .zip file instead. They both use the `plnkr.json` file to flag an example as something to plunker a zip. For example:
+
+```json
+{
+  "description": "Tour of Heroes: Part 6",
+  "basePath": "src/",
+  "files":[
+    "!**/*.d.ts",
+    "!**/*.js",
+    "!**/*.[1,2].*"
+  ],
+  "tags": ["tutorial", "tour", "heroes", "http"]
+}
+```
+
+The zipper will use this information for creating new zips.
+
+## Three kind of examples
+
+The majority of examples in AIO use `System.js` but there are also `CLI` and `Webpack` projects. This tool is able to differentiate between them.
+
+The boilerplate uses a `package.json` that contains packages and scripts tags to run any kind of example. Using that `package.json` in the zips would confuse the users.
+
+Thanks to the `package.json` customizer, we can create a new `package.json` on the fly that would only contain the packages and scripts needed to run that example.
+
+The `exampleZipper.js` won't include any `System.js` related files for `CLI` or `Webpack` projects.
+
+### The package.json customizer
+
+Given a `type`, this tool will populate a `package.json` file customized for that type.
+
+Here you find a:
+
+* **base.json** - All the common scripts and packages
+* **cli.json** - Extra scripts and packages for the CLI
+* **webpack.json** - Extra scripts and packages for Webpack
+* **systemjs.json** - All the system.js related packages but it also contains the remainder scripts that are not in the other files.
+
+The tool will also give some standard names to the scripts. 
+
+## The zipper.json
+
+As mentioned, the tool uses the `plnkr.json` as a flag and also a configuration file for the zipper. The problem is that not all examples have a plunker but they could offer a zip instead.
+
+In those cases, you can create a `zipper.json` file with with the same syntax. It will be ignored by the plunker tool.
+
+## Choosing the zip "type"
+
+In both `plnkr.json` and `zipper.json` you can use two new properties:
+
+```
+{
+  ...
+  "removeSystemJsConfig": true,
+  "type": "webpack"
+}
+```
+
+This would generate a .zip for a webpack application and it will also remove everything related with SystemJS.
+
+## Executing the zip generation
+
+`generateSipz.js` will create a zip for each `plnk.json`  or `zipper.json` it finds.
+
+Where? at `src/generated/zips/`.
+
+Then the `<live-example>` embedded component will look at this folder to get the zip it needs for the example.

aio/tools/plunker-builder/README.md

@@ -47,8 +47,8 @@ To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlu
 
 Where? at `src/generated/live-examples/`.
 
-Then the `<live-example>` embedded component will look at this folder to get the plunker it needs for the example
+Then the `<live-example>` embedded component will look at this folder to get the plunker it needs for the example.
 
 ## Appendix: Why not generating plunkers on runtime?
 
-At AngularJS, all the plunkers were generated a runtime. The downside is that all the example codes would need to be deployed as well and they won't be no longer useful after the plunker is generated. This tool takes a few seconds to run, and the end result is only 3mb~
+At AngularJS, all the plunkers were generated a runtime. The downside is that all the example codes would need to be deployed as well and they won't be no longer useful after the plunker is generated. This tool takes a few seconds to run, and the end result is only 3mb~.