Minor documentation fixes

Readme.md

@@ -16,6 +16,7 @@ React Styleguidist is a style guide generator for React components. It lists com
 * **[Getting Started](./docs/GettingStarted.md): install and run Styleguidist**
 * [Locating components](./docs/Components.md): point Styleguidist to your React components
 * [Configuring webpack](./docs/Webpack.md): tell Styleguidist how to load your code
+* [Documenting components](./docs/Documenting.md): how to write documentation
 * [Cookbook](./docs/Cookbook.md): how to solve common tasks with Styleguidist
 
 ## Examples

docs/CLI.md

@@ -1,6 +1,6 @@
 # CLI commands and options
 
-These commands supposed to be placed in `package.json` `scripts` (see Installation section above). If you want to run them directly, use `./node_modules/.bin/styleguidist`.
+These commands are supposed to be placed in `package.json` `scripts` (see [Getting Started](GettingStarted.md)). If you want to run them directly, use `./node_modules/.bin/styleguidist`.
 
 `styleguidist server`: Run dev server.
 

docs/Components.md

@@ -2,17 +2,9 @@
 
 ## Components
 
-By default Styleguidist will search components using this [glob pattern](https://github.com/isaacs/node-glob#glob-primer): `src/components/**/*.js`. If it doesn’t work for you, create a `styleguide.config.js` file in your project’s root folder.
+By default Styleguidist will search components using this [glob pattern](https://github.com/isaacs/node-glob#glob-primer): `src/components/**/*.js`. It will pick up paths like `src/components/Button.js`, `src/components/Button/Button.js` or `src/components/Button/index.js`. If it doesn’t work for you, create a `styleguide.config.js` file in your project’s root folder and configure the pattern to fit your project structure.
 
-If your components look like `components/Button.js` or `components/Button/Button.js` or `components/Button/index.js` (it’s the default behavior, change only if your components are not in `src/components` or files are not `.js`):
-
-```javascript
-module.exports = {
-  components: 'src/components/**/*.js'
-};
-```
-
-If your components look like `components/Button/Button.js` + `components/Button/index.js` (you need to skip `index.js`, otherwise component will be loaded twice):
+For example, if your components look like `components/Button/Button.js` + `components/Button/index.js` (meaning you need to skip `index.js`, otherwise the component will be loaded twice):
 
 ```javascript
 module.exports = {
@@ -24,7 +16,7 @@ Or you need to skip test specs (`components/Button/Button.test.js`):
 
 ```javascript
 module.exports = {
-  components: 'components/**/!(*.test).js'
+  components: 'src/components/**/!(*.test).js'
 };
 ```
 
@@ -38,8 +30,8 @@ Each section consists of (all fields are optional):
 
 - `name` — section title.
 - `content` — location of a Markdown file containing the overview content.
-- `components` — a string or function returning a list of components. The same rules apply as for the root `components` option.
-- `sections` — array of subsections.
+- `components` — a glob pattern string or a function returning a list of components. The same rules apply as for the root `components` option.
+- `sections` — array of subsections (can be nested).
 
 Configuring a style guide with textual documentation section and a list of components would look like:
 

docs/Configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-You can change settings in the `styleguide.config.js` file in your project’s root folder.
+By default, Styleguidist will look for `styleguide.config.js` file in your project’s root folder. You can change the location of the config file using `--config` [CLI](CLI.md) option.
 
 #### `assetsDir`
 
@@ -194,7 +194,7 @@ module.exports = {
 
 Type: `Array`, optional
 
-Allows components to be grouped into sections with a title and overview content. Sections can also be content only, with no associated components (for example, a textual introduction).
+Allows components to be grouped into sections with a title and overview content. Sections can also be content only, with no associated components (for example, a textual introduction). Sections can be nested.
 
 See examples in the [Sections section](Components.md#sections).
 
@@ -220,7 +220,7 @@ Show or hide example code initially. It can be toggled in the UI by clicking the
 
 Type: `Boolean`, default: `true`
 
-Toggle sidebar initially. Sidebar is being hidden when opening components or examples in the isolation mode even if this value is set to `true`. When set to `false`, sidebar will always be hidden.
+Toggle sidebar visibility. Sidebar will be hidden when opening components or examples in isolation mode even if this value is set to `true`. When set to `false`, sidebar will always be hidden.
 
 #### `skipComponentsWithoutExample`
 
@@ -359,11 +359,11 @@ module.exports = {
 };
 ```
 
-> **Note:**: `output` option will be ignored.
+> **Note:** `output` option will be ignored.
 
-> **Note:**: These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.
+> **Note:** These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.
 
-> **Note:** This option disables webpack config auto load, use `webpackConfigFile` option to load your project’s webpack config from file.
+> **Note:** This option disables webpack config file autoload, use `webpackConfigFile` option to load your project’s webpack config from file.
 
 > **Note:** Run style guide in verbose mode to see the actual webpack config used by Styleguidist: `npm run styleguide -- --verbose`.
 
@@ -381,6 +381,6 @@ module.exports = {
 };
 ```
 
-> **Note:**: `entry`, `externals` and `output` options will be ignored, use `webpackConfig` option to change them.
+> **Note:** `entry`, `externals` and `output` options will be ignored, use `webpackConfig` option to change them.
 
-> **Note:**: These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.
+> **Note:** These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.

docs/Documenting.md

@@ -1,16 +1,18 @@
 # Documenting components
 
-Styleguidist generates documentation from three sources:
+Styleguidist generates documentation for your components based on the comments in your source code, propTypes declarations and Readme files.
 
 > **Note:** [See examples](../examples/basic/lib/components) of documented components in our demo style guide.
 
-## PropTypes and component description in the source code
+## Code comments and propTypes
+
+Styleguidist will display your components’ JSDoc comment blocks. Also, it will pick up props from propTypes declarations and display them in a table.
 
 ```javascript
 import React, { PropTypes } from 'react';
 
 /**
- * General component description.
+ * General component description in JSDoc format. Markdown is *supported*.
  */
 export default class Button extends React.Component {
   static propTypes = {
@@ -38,9 +40,9 @@ export default class Button extends React.Component {
 
 > **Note:** Component’s `PropTypes` and documentation comments are parsed by the [react-docgen](https://github.com/reactjs/react-docgen) library.
 
-## Usage examples and further documentation in Markdown
+## Usage examples and Readme files
 
-Examples are written in Markdown where any code block without a language tag will be rendered as a React component. By default any `Readme.md` or `ComponentName.md` in the component’s folder is treated as an examples file.
+Styleguidist will look for any `Readme.md` or `ComponentName.md` files in the component’s folder and display them. Any code block without a language tag will be rendered as a  React component with live editable preview.
 
     React component example:
 
@@ -58,21 +60,21 @@ Examples are written in Markdown where any code block without a language tag wil
     <Button size="large">Push Me</Button>
     ```
 
-    This example rendered only as highlighted source code:
+    This example is rendered only as highlighted source code, not an actual component:
 
     ```html
     <Button size="large">Push Me</Button>
     ```
 
     Any [Markdown](http://daringfireball.net/projects/markdown/) is **allowed** _here_.
 
-> **Note:** You can change documentation file name with the [getExampleFilename](Configuration.md#getexamplefilename) option.
+> **Note:** You can configure examples file name with the [getExampleFilename](Configuration.md#getexamplefilename) option.
 
 ## External examples using doclet tags
 
-Additional example files can be associated with components using doclet (`@example`) syntax.
+Additional example files can be associated with components using `@example` doclet syntax.
 
-The following component will also have an example as loaded from the `extra.examples.md` file:
+The following component will also have an example loaded from the `extra.examples.md` file:
 
 ```javascript
 /**
@@ -85,9 +87,9 @@ export default class Button extends React.Component {
 }
 ```
 
-## Documenting component public methods
+## Public methods
 
-Mark you public methods with [JSDoc `@public` tag](http://usejsdoc.org/tags-public.html):
+By default, any methods your components have are considered to be private and are not published. Mark your public methods with JSDoc [`@public`](http://usejsdoc.org/tags-public.html) tag to get them published in the docs:
 
 ```javascript
 /**

docs/Webpack.md

@@ -1,14 +1,14 @@
 # Configuring webpack
 
-Styleguidist uses webpack under the hood and needs to know how to load your project’s files.
+Styleguidist uses [webpack](https://webpack.js.org/) under the hood and it needs to know how to load your project’s files.
 
 *Webpack is a peer dependency but your project doesn’t have to use it. React Styleguidist works with webpack 1 and webpack 2.*
 
-> **Note:** [See Cookbook](Cookbook.md) for more examples.
+> **Note:** See [cookbook](Cookbook.md) for more examples.
 
 ## Reusing your project’s webpack config
 
-By default Styleguidist will try to find webpack config (`webpack.config.dev.js` or `webpack.config.js`) anywhere in your project and use it.
+By default Styleguidist will recursively try to find an existing webpack config (`webpack.config.dev.js` or `webpack.config.js`) in your project and use it.
 
 If your webpack config is located somewhere else, add its location to your `styleguide.config.js`:
 
@@ -18,11 +18,11 @@ module.exports = {
 };
 ```
 
-> **Note:**: It may not work with your project, see below for other options.
+> **Note:** It may not work with your project, see below for other options.
 
-> **Note:**: `entry`, `externals` and `output` options will be ignored, use `webpackConfig` option to change them.
+> **Note:** `entry`, `externals` and `output` options will be ignored, use `webpackConfig` option to change them.
 
-> **Note:**: These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.
+> **Note:** These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.
 
 ## Custom webpack config
 
@@ -50,9 +50,9 @@ module.exports = {
 };
 ```
 
-> **Warning:** This option disable webpack config auto load, use `webpackConfigFile` option to load your project’s webpack config from a file.
+> **Warning:** Using this option disables webpack config file autoload, use `webpackConfigFile` option to load your project’s webpack config from a file.
 
-> **Note:**: These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.
+> **Note:** These plugins will be ignored: `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `OccurrenceOrderPlugin`, `DedupePlugin`, `UglifyJsPlugin`, `HotModuleReplacementPlugin`.
 
 ## Non-webpack projects