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

Adding contribution guidelines for the documentation #1086

Merged
merged 3 commits into from
Jan 21, 2020
Merged
Changes from all commits
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
37 changes: 37 additions & 0 deletions Contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,43 @@ Once we've discussed your changes and you've got your code ready, make sure that
* References the original issue in description, e.g. "Resolves #123".
* Has a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).

## Contribution Guidelines for Documentation

* Active Voice

In general use active voice when formulating the sentence instead of passive voice. A sentence written in the active voice will emphasize
the person or thing who is performing an action (eg.The dog chased the ball). In contrast, the passive voice will highlight
the recipient of the action (The ball was chased by the dog). Therefor use the passive voice, only when it's less important
who or what completed the action and more important that the action was completed. For example:

- Recommended: The key-auth plugin authenticates the requests.
- Not recommended: The requests are authenticated by the key-auth plugin.

* Capitalization:

* For titles of a section, capitalize the first letter of each word except for the [closed-class words](http://babelnet.sbg.ac.at/themepark/grammar/classes.htm)
such as determiners, pronouns, conjunctions, and prepositions. Use the following [link](https://capitalizemytitle.com/#Chicago) for guidance.
- Recommended: Authentication **with** APISIX

* For normal sentences don't [capitalize](https://www.grammarly.com/blog/capitalization-rules/) random words in the middle of the sentences.
Use the Chicago manual for capitalization rules for the documentation.

* Second Person

In general, use second person in your docs rather than first person. For example:

- Recommended: You are recommended to use the docker based deployment.
- Not Recommended: We recommend to use the docker based deployment.

* Spellings

Use [American spellings](https://www.oxfordinternationalenglish.com/differences-in-british-and-american-spelling/) when
contributing to the documentation.

* Voice

* Use a friendly and conversational tone. Always use simple sentences. If the sentence is lengthy try to break it in to smaller sentences.

## Do you have questions about the source code?

- **QQ group**: 552030619
Expand Down