[GSoD 2021] Improved contributing guidelines

docusaurus/docs/contributing/blog.md

@@ -53,7 +53,7 @@ This is based on ImageMagick.
 
 Submit your blog by creating a Pull Request at <https://github.com/wechaty/wechaty.js.org/tree/master/jekyll/_posts>
 
-Please make sure the CI turns green, and if the CI fail, you need to check the error messages and fix all the problems before we can continue processing it.
+Please make sure the CI turns green, and if the CI fails, you need to check the error messages and fix all the problems before we can continue processing it.
 
 ## Support
 

docusaurus/docs/contributing/code-of-conduct.md

@@ -0,0 +1,78 @@
+---
+title: Wechaty Community Code of Conduct
+---
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+<https://www.contributor-covenant.org/faq>

docusaurus/docs/contributing/contributor-program.md

@@ -6,11 +6,11 @@ sidebar_label: Contributor program
 
 The _Wechaty Contributor Program_ provides valuable supports for qualified contributors.
 
-> Our Mission: build the most easy to use conversational SDK across all messaging platforms for chatbot makers.
+> Our Mission: build the most easy-to-use conversational SDK across all messaging platforms for chatbot makers.
 
-It takes a community to design, build, and ship great chatbot.
+It takes a community to design, build, and ship a great chatbot.
 
-Building an chatbot that on top of Wechaty? Apply for our Contributor Program! The possibilities are endless, and you enjoy the kudos.
+Building a chatbot that is on top of Wechaty? Apply for our Contributor Program! The possibilities are endless, and you enjoy the kudos.
 
 ## Table of Contents
 
@@ -29,7 +29,7 @@ Learn more about Wechaty Puppet Services from our [document](../puppet-services/
 
 ## 2. Support the Wechaty Project
 
-You can help the project by supporting this project as becoming a backer.  [![Backers on Open Collective](https://opencollective.com/wechaty/backers/badge.svg)](#backers)
+You can help the project by supporting this project as becoming a backer. [![Backers on Open Collective](https://opencollective.com/wechaty/backers/badge.svg)](#backers)
 
 The following are our existing backers. Thank you to everyone! 🙏 [[Become a backer](https://opencollective.com/wechaty#backer)]
 
@@ -39,7 +39,7 @@ The following are our existing backers. Thank you to everyone! 🙏 [[Become a b
 
 [![Wechaty Contributor Program](https://img.shields.io/badge/Wechaty-Contributor%20Program-green.svg)](https://wechaty.js.org/docs/contributing/)
 
-You need to add the __Wechaty Contributor Program__ badge after you join this program.
+You need to add the **Wechaty Contributor Program** badge after you join this program.
 
 ```md
 [![Wechaty Contributor Program](https://img.shields.io/badge/Wechaty-Contributor%20Program-green.svg)](https://wechaty.js.org/docs/contributing/)
@@ -82,7 +82,7 @@ Add this Wechaty badge to your README:
 
 Then add it to the list at [Project using Wechaty](http://wechaty.js.org/docs/case-study/projects-using-wechaty)
 
-## Third Party Supports for Wechaty Contributors
+## Third-Party Supports for Wechaty Contributors
 
 ### Juzi.BOT
 

docusaurus/docs/contributing/devops.md

@@ -8,4 +8,4 @@ To-be-added. (Pull Request is welcome!)
 
 ## Blog
 
-- [Wonderful Wechaty devops toolset, @windmemory, Jun 20, 2020](https://wechaty.js.org/2020/06/20/wonderful-wechaty-devops-tools/)
+- [Wonderful Wechaty DevOps toolset, @windmemory, Jun 20, 2020](https://wechaty.js.org/2020/06/20/wonderful-wechaty-devops-tools/)

docusaurus/docs/contributing/documentation.md

@@ -2,12 +2,24 @@
 title: Write documentation
 ---
 
-We place a high importance on consistency and readability of documentation.
+We place high importance on the consistency and readability of documentation.
 We aim to improve it as often as possible.
 
 Documentation changes generally come in two forms:
 
-- General improvements: typo corrections, error fixes and better
+- General improvements: typo corrections, error fixes, and better
+  explanations through clearer writing and more examples.
+
+---
+
+## title: Write documentation
+
+We place high importance on the consistency and readability of documentation.
+We aim to improve it as often as possible.
+
+Documentation changes generally come in two forms:
+
+- General improvements: typo corrections, error fixes, and better
   explanations through clearer writing and more examples.
 
 - New features: documentation of features that have been added to the
@@ -20,7 +32,7 @@ in the most useful and least error-prone ways.
 
 Though Wechaty's documentation is intended to be read as HTML at
 <https://wechaty.js.org/docs/>, we edit it as a collection of markdown files for
-maximum flexibility. These files live in the top-level ``docusaurus/docs/``
+maximum flexibility. These files live in the top-level `docusaurus/docs/`
 directory at Wechaty Website repository at <https://github.com/wechaty/wechaty.js.org>.
 
 If you'd like to start contributing to our docs, get the latest version of
@@ -46,12 +58,9 @@ Then build the website:
 npm run docusaurus:start
 ```
 
-To get started contributing, you'll want to read the :ref:`reStructuredText
-reference <sphinx:rst-index>`.
-
-Your locally-built documentation will be themed differently than the
+Our locally-built documentation will be themed differently than the
 documentation at [Docusaurus docs introduction](https://docusaurus.io/docs/docs-introduction).
-This is OK! If your changes look good on your local machine, they'll look good
+This is OK! If the changes look good on the local machine, they'll look good
 on the website.
 
 ## How the documentation is organized
@@ -62,15 +71,12 @@ The documentation is organized into several categories:
   of steps to create something.
 
   The important thing in a tutorial is to help the reader achieve something
-  useful, preferably as early as possible, in order to give them confidence.
+  useful, preferably as early as possible, to give them confidence.
 
-  Explain the nature of the problem we're solving, so that the reader
-  understands what we're trying to achieve. Don't feel that you need to begin
-  with explanations of how things work - what matters is what the reader does,
-  not what you explain. It can be helpful to refer back to what you've done and
-  explain afterwards.
+  Explain the nature of the problem we're solving, so that the reader understands what we're trying to achieve. Don't feel that you need to begin with explanations of how things work - what matters is what the reader does,
+  not what you explain. It can be helpful to refer back to what you've done and explain afterward.
 
-- [explanations](explanations/overview.mdx) aim to explain a concept or subject at a
+- [Explainations](explanations/overview.mdx) aim to explain a concept or subject at a
   fairly high level.
 
   Link to reference material rather than repeat it. Use examples and don't be
@@ -85,7 +91,7 @@ The documentation is organized into several categories:
   its use.
 
   Keep reference material tightly focused on the subject. Assume that the
-  reader already understands the basic concepts involved but needs to know or
+  the reader already understands the basic concepts involved but needs to know or
   be reminded of how Wechaty does it.
 
   Reference guides aren't the place for general explanation. If you find
@@ -96,32 +102,33 @@ The documentation is organized into several categories:
   steps in key subjects.
 
   What matters most in a how-to guide is what a user wants to achieve.
-  A how-to should always be result-oriented rather than focused on internal
-  details of how Wechaty implements whatever is being discussed.
+  A how-to should always be result-oriented rather than focused on internal details of how Wechaty implements whatever is being discussed.
 
-  These guides are more advanced than tutorials and assume some knowledge about
-  how Wechaty works. Assume that the reader has followed the tutorials and don't
-  hesitate to refer the reader back to the appropriate tutorial rather than
+  In how-to guides, users are expected to take the initiative and look for the information they need themselves. Contents in this section are organized as recipes to a cookbook. Each topic is independent and is named after the result that users will achieve after they follow the steps inside. With that said, the target audience for this section is those equipped with at least basic knowledge of Wechaty.
+
+  These guides are more advanced than tutorials and assume some knowledge about how Wechaty works. Assume that the reader has followed the tutorials and don't hesitate to refer the reader back to the appropriate tutorial rather than
   repeat the same material.
 
 ## Writing style
 
-When using pronouns in reference to a hypothetical person, such as "a user with
-a session cookie", gender neutral pronouns (they/their/them) should be used.
+When using pronouns about a hypothetical person, such as "a user with
+a session cookie", gender-neutral pronouns (they/their/them) should be used.
 Instead of:
 
 - he or she... use they.
 - him or her... use them.
-- his or her... use their.
+- his or her... use theirs.
 - his or hers... use theirs.
 - himself or herself... use themselves.
 
 Try to avoid using words that minimize the difficulty involved in a task or
 operation, such as "easily", "simply", "just", "merely", "straightforward", and
-so on. People's experience may not match your expectations, and they may become
+so on. People's experience may not match the expectations, and they may become
 frustrated when they do not find a step as "straightforward" or "simple" as it
 is implied to be.
 
+We are following the [Google developer documentation style guide](https://developers.google.com/style). We suggest that you follow it.
+
 ## Commonly used terms
 
 Here are some style guidelines on commonly used terms throughout the
@@ -146,6 +153,10 @@ documentation:
 
 ## Wechaty-specific terminology
 
+- **Bot** &mdash; it's capitalized.
+
+- **Chatbot** &mdash; it's capitalized.
+
 - **Puppet** &mdash; it's capitalized.
 
 - **Puppet Provider** &mdash; it's capitalized.
@@ -154,6 +165,14 @@ documentation:
 
 - **TOKEN** &mdash; it's all capitalized.
 
+- **Wechaty Puppet Service Token** &mdash; it's capitalized.
+
+- **Software Development Kit** &mdash; it's all capitalized.
+
+- **Wechaty gRPC** &mdash; it's all capitalized.
+
+Other than these words we are following this <https://developers.google.com/style/word-list>.
+
 ## Guidelines for Markdown files
 
 These guidelines regulate the format of our MD (Markdown) and MDX (Markdown + JSX)
@@ -165,11 +184,10 @@ documentation:
   is significantly less readable when split over two lines, or for another
   good reason.
 
-- The main thing to keep in mind as you write and edit docs is that the
-  more semantic markup you can add the better. So:
+- The main thing to keep in mind as you write and edit docs is that the more semantic markup you can add the better. So:
 
   ```md
-  Add `django.contrib.auth` to your `INSTALLED_APPS`...
+  Add `django.contrib.auth` to the `INSTALLED_APPS`...
   ```
 
 - Use these heading styles::
@@ -182,10 +200,18 @@ documentation:
   ### Three
 
   #### Four
-    
+
   ##### Five
   ```
 
+  Refer to this for more: <https://guides.github.com/features/mastering-markdown/>.
+
 ## Special Thanks
 
 I have to credit Django doc authors, because this documentation page is inspired by, and mostly copy/pasted from [Django contributing docs](https://github.com/django/django/blob/main/docs/internals/contributing/writing-documentation.txt)
+
+- New features: documentation of features that have been added to the
+  framework since the last release.
+
+This section explains how writers can craft their documentation changes
+in the most useful and least error-prone ways.

docusaurus/docs/contributing/getting-help.md

@@ -0,0 +1,15 @@
+---
+title: Getting Help
+---
+
+## Contact Us
+
+If you have any questions, comments, or concerns, please contact us at:
+
+- You can [join our Gitter](https://gitter.im/wechaty/wechaty) network if you aren’t already a member.
+
+- Join the [Wechaty channel](https://gitter.im/wechaty/wechaty) on Gitter.im and answer questions By explaining Wechaty to other users, you're going to learn a lot about the framework yourself.
+
+- Join the [GitHub Discussions](https://github.com/wechaty/wechaty/discussions). This forum is a place for discussing the Wechaty framework and applications and projects that use it. This is also a good place to ask and answer any questions related to installing, using, or contributing to Wechaty.
+
+- Join the [Google Group](https://groups.google.com/g/wechaty) and answer questions.