storybook/docs/README.md

### Edit Documentation

Documentation is written in Markdown and located inside the [`docs/`](https://github.com/storybookjs/storybook/tree/master/docs/) directory.

Documentation is deployed via the [`frontpage`](https://github.com/storybookjs/frontpage) repository.

### 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 a 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 a third party unless referring to a specific person.
- Refer to contributors and the product as `Storybook`.
- Refer to users as `users`.