Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Updates #3938

Merged
merged 8 commits into from
Aug 1, 2018
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
add guidelines to writing good docs
danielduan committed Jul 31, 2018
commit 5e205a81955ae8f87d1070c92e47733c117b43d1
11 changes: 8 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -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...`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But this is passive voice

* 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...`