Improve docs

readme.md

@@ -1,10 +1,10 @@
 # <img width="250" src="logo.png" alt="chalk">
 
-> Terminal string styling done right.
+> Terminal string styling done right
 
 [![Build Status](https://secure.travis-ci.org/sindresorhus/chalk.png?branch=master)](http://travis-ci.org/sindresorhus/chalk)
 
-[colors.js](https://github.com/Marak/colors.js) is currently the most popular string styling module, but it has serious deficiencies like extending String.prototype which causes all kinds of problems. Although there are other ones, they either do too much or not enough.
+[colors.js](https://github.com/Marak/colors.js) is currently the most popular string styling module, but it has serious deficiencies like extending String.prototype which causes all kinds of [problems](https://github.com/yeoman/yo/issues/68). Although there are other ones, they either do too much or not enough.
 
 **Chalk is a clean and focused alternative.**
 
@@ -18,6 +18,7 @@
 - Clean and focused
 - Auto-detects color support
 - Actively maintained
+- [Used by 150+ modules](https://npmjs.org/browse/depended/chalk)
 
 
 ## Install
@@ -27,25 +28,25 @@ Install with [npm](https://npmjs.org/package/chalk): `npm install --save chalk`
 
 ## Example
 
-Chalk comes with an easy to use composable API where you just chain the styles you want.
+Chalk comes with an easy to use composable API where you just chain and nest the styles you want.
 
 ```js
 var chalk = require('chalk');
 
 // style a string
-console.log(chalk.blue('Hello world!'));
+console.log(  chalk.blue('Hello world!')  );
 
 // combine styled and normal strings
-console.log(chalk.blue('Hello'), 'World' + chalk.red('!'));
+console.log(  chalk.blue('Hello'), 'World' + chalk.red('!')  );
 
 // compose multiple styles using the chainable API
-console.log(chalk.blue.bgRed.bold('Hello world!'));
+console.log(  chalk.blue.bgRed.bold('Hello world!')  );
 
 // nest styles
-chalk.red('Hello', chalk.underline.bgBlue('world') + '!');
+console.log(  chalk.red('Hello', chalk.underline.bgBlue('world') + '!')  );
 
 // pass in multiple arguments
-console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));
+console.log(  chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz')  );
 ```
 
 You can easily define your own themes.
@@ -61,9 +62,11 @@ console.log(error('Error!'));
 
 ### chalk.`<style>[.<style>...](string, [string...])`
 
-Chain [styles](#styles) and call the last one as a method with a string argument.
+Example: `chalk.red.bold.underline('Hello', 'world');`
 
-Multiple arguments are also supported. Chalk will add a space between each one.
+Chain [styles](#styles) and call the last one as a method with a string argument. Order doesn't matter.
+
+Multiple arguments will be separated by space.
 
 ### chalk.enabled
 
@@ -81,6 +84,8 @@ Used internally and handled for you, but exposed for convenience.
 
 Exposes the styles as [ANSI escape codes](https://github.com/sindresorhus/ansi-styles).
 
+Generally not useful, but you might need just the `.open` or `.close` escape code if you're mixing externally styled strings with yours.
+
 ```js
 var chalk = require('chalk');
 
@@ -94,6 +99,19 @@ console.log(chalk.styles.red.open + 'Hello' + chalk.styles.red.close);
 
 [Strip color](https://github.com/sindresorhus/strip-ansi) from a string.
 
+Can be useful in combination with `.supportsColor` to strip color on externally styled text when it's not supported.
+
+Example:
+
+```js
+var chalk = require('chalk');
+var styledString = fromExternal();
+
+if (!chalk.supportsColor) {
+	chalk.stripColor(styledString);
+}
+```
+
 
 ## Styles