Website for storybook.js.org
This is the source for storybook.js.org. It documents Storybook, an amazing UI component development environment for React and React Native. The site is built with Gatsby.
yarn
yarn dev
Documentation is written in Markdown and located inside the docs/src/pages
directory.
- Explain why in addition to how. If something is designed a certain way for a reason, provide that reason.
- Provide examples of code snippets whenever possible - showing is always better than telling.
- 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...
- 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.
- Passive (bad):
- Place action in the verb.
- Indirect action (bad):
A refactor of this code is necessary
. - Direct action (good):
This code needs to be refactored
.
- Indirect action (bad):
- 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...
- Pronoun (bad):
- 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...
- Pronoun (bad):
- 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
.