Merge pull request #773 from misterdev/misterdev-format-scaffold

docs(scaffolding): improved structure, formatting, typos

SCAFFOLDING.md

@@ -2,98 +2,144 @@
 
 Setting up webpack for the first time is hard. Writing advanced configurations to optimize performance is even harder. The `init` feature is designed to support people that want to create their own configuration or initializing other projects people create.
 
-## Writing a good scaffold
+## Creating a scaffold
 
-Before writing a `webpack-cli` scaffold, think about what you're trying to achieve. Do you want a "general" scaffold that could be used by any project or type of app? Do you want something very focused - like a scaffold that writes both your `webpack.config.js` and your framework code? It's also useful to think about the user experience for your scaffold.
+Before writing a `webpack-cli` scaffold, think about what you're trying to achieve. Do you want a "general" scaffold that could be used by any project or type of app? Do you want something very focused, like a scaffold that writes both your `webpack.config.js` and your framework code? It's also useful to think about the user experience for your scaffold.
 
 `webpack-cli` offers an experience that is interactive and you can prompt users for questions (like, "What is your entry point?") to help customize the output accordingly.
 
-## webpack-scaffold
+### Writing a scaffold
 
-`webpack-scaffold` is a utility suite for creating scaffolds. It contains functions that could be of use for creating an scaffold yourself.
+There are many resources where you can learn how to write a scaffold, you can start from: [How do I compose a
+webpack-scaffold?](https://github.com/evenstensberg/webpack-scaffold-demo)
 
-## webpack-scaffold-yourpackage
 
-In order for `webpack-cli` to compile your package, it must be available on npm or on your local filesystem. If you are curious about how you can create your very own `scaffold`, please read [How do I compose a
-webpack-scaffold?](https://github.com/evenstensberg/webpack-scaffold-demo).
+[`webpack-scaffold`](./packages/webpack-scaffold) is a utility suite for creating scaffolds. It contains functions that could be used to create a scaffold.
 
-If the package is on npm, its name must have a prefix of `webpack-scaffold`.
 
-If the package is on your local filesystem, it can be named whatever you want. Pass the path to the package.
+### Running a scaffold
+
+A scaffold can be executed using [`webpack-cli init`](./INIT.md): 
+
+```js
+webpack-cli init <your-scaffold>
+```
+
+#### Running a scaffold locally
+When the scaffold package is in your local file system you should pass its path to `init`:
+
+```bash
+webpack-cli init path/to/your/scaffold
+```
+
+Or you can create a global module and symlink to the local one:
+
+* Using npm
+
+	```bash
+	cd path/to/my-scaffold
+	npm link
+	webpack-cli init my-scaffold
+	```
+
+* Using yarn
+
+	```bash
+	cd path/to/my-scaffold
+	yarn link
+	webpack-cli init my-scaffold
+
+#### Running a scaffold from npm
+
+If the package is in npm, its name must begin with `webpack-scaffold` and can be used running:
+
+```js
+webpack-cli init webpack-scaffold-yourpackage
+```
+
 
 ## API
 
-To create a `scaffold`, you must create a [`yeoman-generator`](http://yeoman.io/authoring/). Because of that, you can optionally extend your generator to include methods from the [Yeoman API](http://yeoman.io/learning/). Its worth noting that we support all the properties of a regular webpack configuration. In order for us to do this, there's a thing you need to remember.
+To create a `scaffold`, you must create a [`yeoman-generator`](http://yeoman.io/authoring/). Because of that, you can optionally extend your generator to include methods from the [Yeoman API](http://yeoman.io/learning/). It's worth noting that we support all the properties of a regular webpack configuration. In order for us to do this, there's a thing you need to remember:
 
-Objects are made using strings, while strings are made using double strings. This means that in order for you to create an string, you have to wrap it inside another string for us to validate it correctly.
+> Objects are made using strings, while strings are made using double strings. This means that in order for you to create a string, you have to wrap it inside another string for us to validate it correctly.
 
+### Required
+- [opts.env.configuration](#optsenvconfiguration-required)
+- [opts.env.configuration.myObj](#optsenvconfigurationmyObj-required)
+- [myObj.webpackOptions](#myObjwebpackOptions-required)
+- [writing()](#writing()-required)
+
+### Optional
+- [myObj.merge](#myObjmerge-optional)
+- [myObj.topScope](#myObjtopScope-optional)
+- [myObj.configName](#myObjconfigName-optional)
 
 ### `opts.env.configuration`(required)
 
-Initialized inside the constructor of your generator in order for the CLI to work.
+This is the entry point your configuration, initialize it inside the constructor of your generator in order for the CLI to work:
 
 ```js
 constructor(args, opts) {
-		super(args, opts);
-		opts.env.configuration = {};
-	}
+	super(args, opts);
+	opts.env.configuration = {};
+}
 ```
 ### `opts.env.configuration.myObj` (required)
 
-`myObj` is your scaffold. This is where you will add options for the CLI to transform into a configuration. You can name it anything, and you can also add more objects, that could represent a `dev.config` or `prod.config`.
+This is your scaffold, you add here the options that the CLI will transform into a webpack configuration. You can have many different scaffolds named as you prefer, representing different configurations like `dev.config` or `prod.config`:
 
 ```js
 constructor(args, opts) {
-		super(args, opts);
-		opts.env.configuration = {
-			dev: {},
-			prod: {}
-		};
-	}
+	super(args, opts);
+	opts.env.configuration = {
+		dev: {},
+		prod: {}
+	};
+}
 ```
 
 ### `myObj.webpackOptions` (required)
 
-As with a regular webpack configuration, this property behaves the same. Inside `webpackOptions` you can declare the properties you want to scaffold. You can for instance, scaffold `entry`, `output` and `context`.
+This object has the same format as a regular webpack configuration, so you declare here the properties that you want to scaffold, like `entry`, `output` and `context`. You can initialize this inside a yeoman method:
 
-(Inside a yeoman method)
 ```js
 this.options.env.configuration.dev.webpackOptions = {
-entry: '\'app.js\'',
-output: {....}
+	entry: '\'app.js\'',
+	output: {...}
 };
 ```
 
 ### `myObj.merge` (optional)
 
-If you want to use `webpack-merge`, you can supply `merge` with the merge property, and the configuration you want to merge it with. 
+If you want to use [`webpack-merge`](https://github.com/survivejs/webpack-merge), you can set the `merge` property of `myObj` to the name of the configuration you want to merge it with: 
 
 ```js
 this.options.env.configuration.dev.merge = 'myConfig';
 ```
 
 ### `myObj.topScope`(optional)
 
-The `topScope` property is a way for the authors to add special behaviours, like functions that could be called inside a configuration, or variable initializations and module imports. 
+The `topScope` property is where you write all the code needed by your configuration, like module imports and functions/variables definitions:
 
 ```js
 this.options.env.configuration.dev.topScope = [
-'var webpack = require(\'webpack\');'
-'var path = require(\'path\');'
+	'const webpack = require(\'webpack\');',
+	'const path = require(\'path\');'
 ];
 ```
 
 ### `myObj.configName`(optional)
 
-If you want to name your `webpack.config.js` something special, you can do that.
+`configName` allows you to customize the name of your configuration file. For example you can name it `webpack.base.js` instead of the default `webpack.config.js`:
 
 ```js
 this.options.env.configuration.dev.configName = 'base';
 ```
 
 ### `writing` (required)
 
-For the scaffolding instance to run, you need to write your configuration to a `.yo-rc.json` file. This could be done using one of the lifecycles in the yeoman generator, such as the `writing` method.
+For the scaffolding instance to run, you need to write your configuration to a `.yo-rc.json` file. This could be done using one of the lifecycles in the yeoman generator, such as the `writing` method:
 
 ```js
 writing() {