From 15b1073891c9ad63d614a064e9b016edb543e12c Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Thu, 26 Jul 2018 16:59:45 -0400 Subject: [PATCH 1/8] edit introduction --- docs/src/pages/basics/introduction/index.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/src/pages/basics/introduction/index.md b/docs/src/pages/basics/introduction/index.md index da8be2020027..5dc0e48568ba 100644 --- a/docs/src/pages/basics/introduction/index.md +++ b/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. +With it, users can 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 your app so you 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) From 99a195a1a43166393d8cfc166715467215de003f Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Thu, 26 Jul 2018 17:07:06 -0400 Subject: [PATCH 2/8] update quick start guide --- docs/src/pages/basics/quick-start-guide/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/src/pages/basics/quick-start-guide/index.md b/docs/src/pages/basics/quick-start-guide/index.md index 52d0b49c8d46..34467eeb6140 100644 --- a/docs/src/pages/basics/quick-start-guide/index.md +++ b/docs/src/pages/basics/quick-start-guide/index.md @@ -3,28 +3,28 @@ 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 our 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 your existing projects. To avoid the global install and setup your project manually, take a look at our [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: +You can run your Storybook with: ```sh npm run storybook ``` -Then you can access your storybook from the browser. +Storybook should now be available in your browser with the link provided in the console. * * * @@ -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). +If you prefer a guided tutorial to reading docs, head to [Learn Storybook](https://www.learnstorybook.com) for a step-by-step guide (only available for React). From b036f121406378aa19283c6f42d843c4813af1a5 Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Thu, 26 Jul 2018 17:07:43 -0400 Subject: [PATCH 3/8] update slow start guide --- docs/src/pages/basics/slow-start-guide/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/pages/basics/slow-start-guide/index.md b/docs/src/pages/basics/slow-start-guide/index.md index 85fdb38369b0..b920a2889306 100644 --- a/docs/src/pages/basics/slow-start-guide/index.md +++ b/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/) From 672c845b9ddcae0ee925169fb91bba31addbd6a3 Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Thu, 26 Jul 2018 17:35:54 -0400 Subject: [PATCH 4/8] rephrase writing stories --- docs/src/pages/basics/writing-stories/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/src/pages/basics/writing-stories/index.md b/docs/src/pages/basics/writing-stories/index.md index bad3692f69bf..9f8a0c2d2de3 100644 --- a/docs/src/pages/basics/writing-stories/index.md +++ b/docs/src/pages/basics/writing-stories/index.md @@ -3,21 +3,21 @@ 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, it's easier to maintain stories that 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. +It's always possible to edit the storybook config file and ask it to load stories from other folders too. -## Writing stories +## Writing Stories This is how you write stories: (Let's assume there's a component called "Button" in `src/components/Button.js`.) From 4b8735788724e76d3f6fc5b837b6de475e01fe9a Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Tue, 31 Jul 2018 14:13:51 -0400 Subject: [PATCH 5/8] add guidelines to writing good docs --- docs/README.md | 20 ++++++++++++++++ .../src/pages/basics/writing-stories/index.md | 24 +++++++++---------- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 58da5e7675dd..acc11b654f46 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,3 +13,23 @@ 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 + +1. Provide examples of code snippets whenever possible. +2. 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.` +3. 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. +4. 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...` diff --git a/docs/src/pages/basics/writing-stories/index.md b/docs/src/pages/basics/writing-stories/index.md index 9f8a0c2d2de3..bcf14bb06904 100644 --- a/docs/src/pages/basics/writing-stories/index.md +++ b/docs/src/pages/basics/writing-stories/index.md @@ -11,11 +11,11 @@ A Storybook can be comprised of many stories for many components. ## Location for Stories -There are no rules for this, but in general, it's easier to maintain stories that are located closer to components. +There are no rules for this, but in general, stories are easier to maintain when they are located closer to components. -For example, if the UI components live in a directory called: `src/components.`, then the stories can be written 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. -It's always possible to edit the storybook config file and ask it to load stories from other folders too. +The Storybook config file can also be edited to load stories from other folders too. ## Writing Stories @@ -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 our 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, it is necessary to load stories 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 on centering all components: ```js import React from 'react'; @@ -84,9 +84,9 @@ storiesOf('MyComponent', module) .add('with some props', () => ); ``` -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'; From 5e205a81955ae8f87d1070c92e47733c117b43d1 Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Tue, 31 Jul 2018 14:22:02 -0400 Subject: [PATCH 6/8] add guidelines to writing good docs --- docs/README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index acc11b654f46..19372603da09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,22 +14,27 @@ yarn storybook 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 +### Guidelines for Writing Good Documentation 1. Provide examples of code snippets whenever possible. 2. 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`. 3. 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 + * 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. -4. Avoid simplifying problems - this frustrates users even more when they don't understand something "simple": + * Refer to us contributors and the product as `Storybook`. + * Refer to users as `users`. +4. 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...` From bd1e39e3efb42028d6a6ba3586d9ff307442b98c Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Tue, 31 Jul 2018 14:34:55 -0400 Subject: [PATCH 7/8] refine docs --- docs/README.md | 18 ++++++++++-------- docs/src/pages/basics/writing-stories/index.md | 16 ++++++++-------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/README.md b/docs/README.md index 19372603da09..37719f31291d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,15 +16,21 @@ Documentation is written in Markdown and located inside the [`docs/src/pages`](h ### Guidelines for Writing Good Documentation -1. Provide examples of code snippets whenever possible. -2. Use concise language - The less time users spend on reading and understanding docs, the better. +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`. -3. Avoid the use of pronouns - documentation should not address the reader because not everything applies to the person reading our docs. +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...` @@ -32,9 +38,5 @@ Documentation is written in Markdown and located inside the [`docs/src/pages`](h - 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 us contributors and the product as `Storybook`. + * Refer to contributors and the product as `Storybook`. * Refer to users as `users`. -4. 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...` diff --git a/docs/src/pages/basics/writing-stories/index.md b/docs/src/pages/basics/writing-stories/index.md index bcf14bb06904..20d87e9ad06b 100644 --- a/docs/src/pages/basics/writing-stories/index.md +++ b/docs/src/pages/basics/writing-stories/index.md @@ -19,7 +19,7 @@ The Storybook config file can also be edited to load stories from other folders ## 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 @@ -45,11 +45,11 @@ This will add stories in the storybook like this: ![Basic stories](../static/basic-stories.png) -This uses our basic API for writing stories. There are official and third party Storybook [addons](/addons/introduction) for more advanced 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, it is necessary to load stories dynamically rather than explicitly in the Storybook config file. +Sometimes, stories need to be loaded dynamically rather than explicitly in the Storybook config file. 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: @@ -71,7 +71,7 @@ The **React Native** packager resolves all the imports at build-time, so it's no ## Using Decorators -A decorator is a way to wrap a story with a common set of components. Here is an example on centering all components: +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'; @@ -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', () => , { ## 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 { From 9a1eadd214706ad75b2a5fd988d456fba8569f63 Mon Sep 17 00:00:00 2001 From: Daniel Duan Date: Tue, 31 Jul 2018 14:53:02 -0400 Subject: [PATCH 8/8] fix pronouns --- docs/src/pages/basics/introduction/index.md | 4 ++-- docs/src/pages/basics/quick-start-guide/index.md | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/src/pages/basics/introduction/index.md b/docs/src/pages/basics/introduction/index.md index 5dc0e48568ba..58ae0b039fb2 100644 --- a/docs/src/pages/basics/introduction/index.md +++ b/docs/src/pages/basics/introduction/index.md @@ -4,9 +4,9 @@ title: 'Introduction' --- Storybook is a UI development environment and playground for UI components. -With it, users can create components independently and showcase components interactively in an isolated development environment. +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) diff --git a/docs/src/pages/basics/quick-start-guide/index.md b/docs/src/pages/basics/quick-start-guide/index.md index 34467eeb6140..4307b38ebd18 100644 --- a/docs/src/pages/basics/quick-start-guide/index.md +++ b/docs/src/pages/basics/quick-start-guide/index.md @@ -6,29 +6,29 @@ title: 'Quick Start Guide' 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 our automated command line tool. This command adds a set of boilerplate files for Storybook in your project: +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 setup 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 ``` -You can run your Storybook with: +Start Storybook with: ```sh npm run storybook ``` -Storybook should now be available in your browser with the link provided in the console. +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 (only available for React). +A tutorial is also available at [Learn Storybook](https://www.learnstorybook.com) for a step-by-step guide (only available for React).