Merge pull request #3938 from storybooks/dd/doc-updates

Documentation Updates

docs/README.md

@@ -13,3 +13,30 @@ yarn storybook
 ### Edit Documentation
 
 Documentation is written in Markdown and located inside the [`docs/src/pages`](https://github.com/storybooks/storybook/tree/master/docs/src/pages) directory.
+
+### Guidelines for Writing Good Documentation
+
+0. Explain **why** in addition to **how**. If something is designed a certain way for a reason, provide that reason.
+1. Provide examples of code snippets whenever possible - showing is always better than telling.
+2. Avoid simplifying problems - this frustrates users even more when they don't understand something "simple".
+  * Bad examples:
+    - `All you need to do is apply...`
+    - `Simply add...`
+    - `The object is just...`
+3. Use concise language - The less time users spend on reading and understanding docs, the better.
+  * Avoid using passive voice.
+    - Passive (bad): `It is believed by Storybook that empowering component builders is important.`
+    - Active (good): `Storybook believes in empowering component builders.`
+  * Place action in the verb.
+    - Indirect action (bad): `A refactor of this code is necessary`.
+    - Direct action (good): `This code needs to be refactored`.
+4. Avoid the use of pronouns - documentation should not address the reader because not everything applies to the person reading our docs.
+  * Don't use `you` to refer to the user or third party.
+    - Pronoun (bad): `You can also...`
+    - Without pronoun (good): `Users can also...`
+  * Don't use `we` to refer to Storybook, contributors, or Storybook users.
+    - Pronoun (bad): `We can create this component...`
+    - Without pronoun (good): `The component can be created...`
+  * Don't use `he`, `she`, `him`, `her`, etc. to refer to third party unless referring to a specific person.
+  * Refer to contributors and the product as `Storybook`.
+  * Refer to users as `users`.

docs/src/pages/basics/introduction/index.md

@@ -3,18 +3,17 @@ id: 'introduction'
 title: 'Introduction'
 ---
 
-Storybook is a UI development environment for your UI components.
-With it, you can visualize different states of your UI components and develop them interactively.
+Storybook is a UI development environment and playground for UI components.
+The tool enables users to create components independently and showcase components interactively in an isolated development environment.
 
-Storybook runs outside of your app.
-So you can develop UI components in isolation without worrying about app specific dependencies and requirements.
+Storybook runs outside of the main app so users can develop UI components in isolation without worrying about app specific dependencies and requirements.
 
 ![Storybook](../static/screenshot.png)
 
-Storybook also comes with a lot of [addons](/addons/introduction) and a great API to customize as you wish.
-You can also build a [static version](/basics/exporting-storybook) of your storybook and deploy it anywhere you want.
+Storybook also supports a lot of [addons](/addons/introduction) and comes with a flexible API to customize Storybook as desired.
+A [Static version](/basics/exporting-storybook) of Storybook can also be built and deployed to an HTTP server.
 
-Here are some featured storybooks that you can reference to see how Storybook works:
+Here are some featured Storybooks to see how it works:
 
 -   [Demo of React Dates](http://airbnb.io/react-dates/) - [source](https://github.com/airbnb/react-dates)
 -   [Demo of React Native Web](http://necolas.github.io/react-native-web/storybook/) - [source](https://github.com/necolas/react-native-web)

docs/src/pages/basics/quick-start-guide/index.md

@@ -3,32 +3,32 @@ id: 'quick-start-guide'
 title: 'Quick Start Guide'
 ---
 
-Storybook is very easy to use. You can use it with any kind of React or Vue or Angular or Mithril project.
-Follow these steps to get started with Storybook.
+Storybook supports many different frontend frameworks with more coming!
+React, Vue, Angular, Mithril, Marko, and HTML are currently supported. Follow these steps to get started with Storybook.
 
+Get started using the automated command line tool. This command adds a set of boilerplate files for Storybook in your project:
 ```sh
 cd my-project-directory
 npm i -g @storybook/cli
 getstorybook
 ```
-The `-g` global install is used to run our cli tool in your project directory to generate templates for your existing projects. To avoid the global install and start your project manually, take a look at our [Slow Start Guide](/basics/slow-start-guide/).
+The `-g` global install is used to run our cli tool in your project directory to generate templates for existing projects. To avoid the global install and setup a project manually, take a look at the [Slow Start Guide](/basics/slow-start-guide/).
 
 To install storybook for HTML, add `--html` argument:
 ```
 getstorybook --html
 ```
-
-This will configure your app for Storybook. After that, you can run your Storybook with:
 
+Start Storybook with:
 ```sh
 npm run storybook
 ```
 
-Then you can access your storybook from the browser.
+Storybook should now be available in the browser with a link provided in the console.
 
 * * *
 
-To learn more about what `getstorybook` command does, have a look at our slow start guides:
+To learn more about what `getstorybook` command does, have a look at the slow start guides:
 * [React](/basics/guide-react/)
 * [Vue](/basics/guide-vue/)
 * [Angular](/basics/guide-angular/)
@@ -37,4 +37,4 @@ To learn more about what `getstorybook` command does, have a look at our slow st
 * [HTML](/basics/guide-html/)
 
 
-If you prefer a guided tutorial to reading docs, head to [Learn Storybook](https://www.learnstorybook.com) for a step-by-step guide (currently React-only).
+A tutorial is also available at [Learn Storybook](https://www.learnstorybook.com) for a step-by-step guide (only available for React).

docs/src/pages/basics/slow-start-guide/index.md

@@ -1,9 +1,9 @@
 ---
 id: 'slow-start-guide'
-title: 'Slow start guide'
+title: 'Slow Start Guide'
 ---
 
-Storybook supports multiple UI libraries. The manual setup for each is different:
+Storybook supports multiple UI libraries. The manual setup for each framework is different:
 
 -   [Storybook for React](/basics/guide-react/)
 -   [Storybook for Vue](/basics/guide-vue/)

docs/src/pages/basics/writing-stories/index.md

@@ -3,23 +3,23 @@ id: 'writing-stories'
 title: 'Writing Stories'
 ---
 
-Storybook is all about writing stories. Usually a story contains a single state of one of your components. That's like a visual test case.
+Storybook is all about writing stories. A story usually contains a single state of one component, almost like a visual test case.
 
 > Technically, a story is a function that returns a React element.
 
-You can write a set of stories for your components and you'll get a storybook.
+A Storybook can be comprised of many stories for many components.
 
-## Keeping your stories
+## Location for Stories
 
-There's no hard and fast rule for this. But, keeping stories close to your components is a good idea.
+There are no rules for this, but in general, stories are easier to maintain when they are located closer to components.
 
-For example, let's say your UI components live in a directory called: `src/components.` Then you can write stories inside the `src/stories` directory.
+For example, if the UI components live in a directory called: `src/components`, then the stories can be written inside the `src/stories` directory.
 
-This is just one way to do that. You can always edit your storybook config file and ask it to load stories from anywhere you want.
+The Storybook config file can also be edited to load stories from other folders too.
 
-## Writing stories
+## Writing Stories
 
-This is how you write stories:
+Here is an example of a basic story:
 (Let's assume there's a component called "Button" in `src/components/Button.js`.)
 
 ```js
@@ -41,17 +41,17 @@ storiesOf('Button', module)
   ));
 ```
 
-This will show stories in your storybook like this:
+This will add stories in the storybook like this:
 
 ![Basic stories](../static/basic-stories.png)
 
-This is just our core API for writing stories. In addition to this, you can use the official and third party Storybook [addons](/addons/introduction) to get more functionality.
+This uses Storybook's basic API for writing stories. There are official and third party Storybook [addons](/addons/introduction) for more advanced functionality.
 
 ## Loading stories dynamically
 
-Sometimes, you will want to load your stories dynamically rather than explicitly requiring them in the Storybook config file.
+Sometimes, stories need to be loaded dynamically rather than explicitly in the Storybook config file.
 
-For example, you may write stories for your app inside the `src/components` directory with the `.stories.js` extension. Then you will want to load them at once. Simply edit your config directory at `.storybook/config.js` as follows:
+For example, the stories for an app may all be inside the `src/components` directory with the `.stories.js` extension. It is easier to load all the stories automatically like this inside the `.storybook/config.js` file:
 
 ```js
 import { configure } from '@storybook/react';
@@ -65,13 +65,13 @@ function loadStories() {
 configure(loadStories, module);
 ```
 
-Here we use Webpack's [require.context](https://webpack.js.org/guides/dependency-management/#require-context) to load modules dynamically. Have a look at the relevant Webpack [docs](https://webpack.js.org/guides/dependency-management/#require-context) to learn more about how to use require.context.
+Storybook uses Webpack's [require.context](https://webpack.js.org/guides/dependency-management/#require-context) to load modules dynamically. Take a look at the relevant Webpack [docs](https://webpack.js.org/guides/dependency-management/#require-context) to learn more about how to use `require.context`.
 
-The **React Native** packager resolves all the imports at build-time, so it's not possible to load modules dynamically. If you don't want to import all your stories manually you can use [react-native-storybook-loader](https://github.com/elderfo/react-native-storybook-loader) to automatically create the import statements for all of your stories.
+The **React Native** packager resolves all the imports at build-time, so it's not possible to load modules dynamically. There is a third party loader  [react-native-storybook-loader](https://github.com/elderfo/react-native-storybook-loader) to automatically generate the import statements for all stories.
 
 ## Using Decorators
 
-A decorator is a way to wrap a story with a common set of component(s). Let's say you want to center all your stories. Here is how we can do this with a decorator:
+A decorator is a way to wrap a story with a common set of components. Here is an example for centering all components:
 
 ```js
 import React from 'react';
@@ -84,9 +84,9 @@ storiesOf('MyComponent', module)
   .add('with some props', () => <MyComponent text="The Comp" />);
 ```
 
-Here we only add the decorator for the current set of stories. (In this example, we add it just for the **MyComponent** story group.)
+This only applies the decorator to the current set of stories. (In this example, the decorator is added only to the **MyComponent** story group.)
 
-But, you can also add a decorator **globally** and it'll be applied to all the stories you create. This is how to add a decorator like that:
+It is possible to apply a decorator **globally** to all the stories. Here is an example of the Storybook config file:
 
 ```js
 import React from 'react';
@@ -101,7 +101,7 @@ configure(function() {
 
 ## Using Markdown
 
-As of storybook 3.3, [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) can be used in storybook by default. All you need to do is import a markdown file, which extracts the raw markdown content into a string. You can then use that string in any addon that supports markdown (such as notes).
+As of storybook 3.3, [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) can be used in Storybook by default. Users can import a markdown file which extracts the raw markdown content into a string. The string can then be used in any addon that supports markdown such as notes and info.
 
 ```js
 import React from 'react';
@@ -116,7 +116,7 @@ storiesOf('Component', module).add('With Markdown', () => <MyComponent />, {
 
 ## Nesting stories
 
-You can organize your stories in a nesting structures using "/" as a separator:
+Stories can be organized in a nested structure using "/" as a separator:
 
 ```js
 // file: src/stories/index.js
@@ -140,7 +140,7 @@ storiesOf('My App/Buttons/Emoji', module).add('with some emoji', () => (
 
 ## Generating nesting path based on \_\_dirname
 
-The name is just a javascript string, by using a template literal, you can easily interpolate data.
+Nesting paths can be programmatically generated with template literals because story names are strings.
 
 One example would be to use `base` from [`paths.macro`](https://github.com/storybooks/paths.macro):
 
@@ -161,7 +161,7 @@ _This uses [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macr
 
 ## Run multiple storybooks
 
-You can run multiple storybooks for different kinds of stories (or components). To do that, you can create different NPM scripts to start different stories. See:
+Multiple storybooks can be built for different kinds of stories or components in a single repository by specifying different port numbers in the start scripts:
 
 ```json
 {