Hello Wechaty GSoD’21 Technical Writers!

It’s a great honor for Wechaty to participate in Google Season of Docs 2021 as one of the great top 30 open-source sponsored projects all over the world！

The most important thing is, the GSoD program helps Wechaty organization to start collaborating with many great technical writers all over the world for improving the documentation of Wechaty project.

If you have read our blog post Google Season of Docs ❤️ Wechaty, @huan, Apr 30, 2021, then you must known that we have 15 technical writers have sent proposals before our deadline May 1st. After that, before we have the kickoff zoom meeting on May 8, we have been contacted by total 24 technical writers, which is the most powerful writers team I have ever seen before!

Technical writer selection

According to the timeline from GSoD’21, we need to hire the technical writers for our organization before May 17, 2021 at 18:00 UTC.

In order to select the most suitable writers for the Wechaty organization, we have lots of conversations between the mentors and the candidates in our Gitter channel and Mailing list.

After reviewing the proposal and having conversation with all the participants, we decided to splict the GSoD’21 to one primary project and five secondary projects for the Wechaty GSoD’21 program:

1. Create easy to learn tutorials for beginner users of Wechaty (the primary project)
2. Improve the How-to guides section
3. Improve the References section
4. Improve the Explanations (and Introduction) sections
5. Reconstruct Wechaty homepage(landing page) with value proposition
6. Improve the gRPC and OpenAPI ecosystem

As well as we will have two volunteer for helping mentors to manage the project and make sure everything is on track.

Attendees

There are total 20 attendees on our meeting. They are:

1. Huan, Creator of Wechaty, UTC+8
2. Rui, Co-creator of Wechaty, UTC+8
3. Rohitesh, GSoD’20 participant & interested in Volunteering for GSoD’21, UTC +5:30
4. Jaya Gupta
5. Vasvi Sood
6. Ahmed Essam, GSoD’21 participant, GMT+2
7. Sajen Sarvajith K, GSoD’21 participant,, UTC+05:30
8. Soumi Bardhan, GSoD’21 participant, UTC+5:50
9. Abhishek Jaiswal,GSoD’21 participant, UTC+05:30
10. Simin Liao, GSoD’21 participant and volunteer, UTC+8
11. Shwetal Soni, GSOD’21 participant, UTC+05:30
12. Mukosa Joseph Mawa, GSOD’21 participant, UTC +03:00
13. Rufai Mustapha, GSOD’21 participant, UTC +01:00
14. Souvik Biswas, GSoD’21 participant, UTC +05:30
15. Shraddha Prasad , GSoD’21 participant, UTC +05:30
16. Anirudh T.P.V.S, GSoD’21 participant, UTC+8
17. Chris Estepa, GSoD’21 participant, UTC +8
18. David Atanda, GSoD’21 participant, UTC +1
19. Arnab Saha,GSod’21 participant(landing pages)
20. Rajiv Ranjan Singh, GSoD 2021 participant, (UTC+05:30)

The Zoom Meeting

We have great conversations with our GSoD’21 participants, and after the deadline of receiving proposals April 30, we organized a zoom meeting with all our technical writers.

In this meeting, all the GSoD’21 participants introduceed theirselves and presented their proposals for the projects that they applied. Huan and Rui introduced the Wechaty project and community to the writer team.

The following YouTube video is the 3 hours recording of our great kick-off meeting of Wechaty GSoD’21 program:

Agendas

• 0:01:41 1. Introducing the Meeting Agenda
• 0:03:08 2. Self-introduction: Huan
• 0:06:15 3. Self-introduction: Rui
• 0:09:15 4. Self-introducing: Technical Writers
• 0:24:53 5. Introducing Wechaty
• 0:29:37 6. Introducing GSoD Project List
• 0:41:46 7. Introducing Received Proposals
• 0:44:41 8. Primary Project: Tutorial
• 0:45:33 8.1 Tutorial Proposal from Souvik Biswas
• 0:49:24 8.2 Tutorial Proposal from Shwetal Soni
• 1:00:19 9. Landing Page Proposal from Sajen Sarvajith K
• 1:12:00 10. Introduction & Explanation Proposal from Mukosa Joseph Mawa
• 1:23:44 11.1. How-to Guides Proposal from Vasvi Sood
• 1:27:38 11.2. How-to Guides Proposal from Abhishek Jaiswal
• 1:33:05 12. References Proposal from Shraddha Vasant Prasad
• 1:41:00 13. Volunteer Project
• 1:43:00 13.1 Volunteer Proposal from Rohitesh Jain
• 1:45:42 13.2 Volunteer Proposal from Vicky Liao
• 1:57:49 14. Budget Plan for Stipends
• 2:05:28 15. Webmaster Tools
• 2:06:33 16. Q&A

You can learn more from our meeting notes.

---

Documentation style guide

We should always follow the Google developer documentation style guide, which provides for anyone writing developer documentation.

Learn more from Google technical writing resources

Documentation system

Wechaty documentation has been adapted to the documentation system by @huan on Mar 25, 2021.

We should always follow the documentation system by strictly aligning our docs to the following chart:

Learn more from:

1. Documentation System Official Website
2. YouTube: What nobody tells you about documentation, Daniele Procida, 2017, PyCon AU

GSoD’21 projects brief

The project 1-4 is strictly defined by the documentation system, and they must follow the do not go out of scope rule:

Credit: Documentation system: Introduction

Project 1: Tutorials

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it.

They are wholly learning-oriented, and specifically, they are oriented towards learning how rather than learning that.

You are the teacher, and you are responsible for what the student will do. Under your instruction, the student will execute a series of actions to achieve some end.

The end and the actions are up to you, but deciding what they should be can be hard work. The end has to be meaningful, but also achievable for a complete beginner.

Learn more from Documentation system: tutorials

Project 2: How-to guides

How-to guides take the reader through the steps required to solve a real-world problem.

They are recipes, directions to achieve a specific end.

For examples:

1. how to create a web form;
2. how to plot a three-dimensional data-set;
3. how to enable LDAP authentication.

They are wholly goal-oriented.

How-to guides are wholly distinct from tutorials and must not be confused with them:

• A tutorial is what you decide a beginner needs to know.
• A how-to guide is an answer to a question that only a user with some experience could even formulate.

Learn more from Documentation system: how-to guides

Project 3: Reference

Reference guides are technical descriptions of the machinery and how to operate it.

Reference guides have one job only: to describe. They are code-determined, because ultimately that’s what they describe:

1. key classes
2. functions
3. APIs

and so they should list things like:

1. functions
2. fields
3. attributes
4. methods

and set out how to use them.

Reference material is information-oriented.

By all means technical reference can contain examples to illustrate usage, but it should not attempt to explain basic concepts, or how to achieve common tasks.

Reference material should be austere and to the point.

Learn more from Documentation system: reference

Project 4: Explanation

Explanation, or discussions, clarify and illuminate a particular topic. They broaden the documentation’s coverage of a topic.

They are understanding-oriented.

Explanations can equally well be described as discussions; they are discursive in nature. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.

Learn more from Documentation system: explanation

Project 5: Landing page with value proposation

We has been planning to reconstruct Wechaty landing page with value propositions for a long time.

The Value Proposition is a statement that answers the ‘why’ someone should do business with you.

It should convince a potential customer why your service or product will be of more value to them than similar offerings from your competition.

You know why your company is great, but do your potential customers know what sets your brand apart?

It must tell your audience:

1. How your product or service solves/improves problems
2. What benefits customers can expect
3. Why customers should buy from you over your competitors

It introduces you to prospective buyers and helps you make a strong first impression. That’s why it is so important to have a powerful one.

Learn more about the value proposition from this great article: The 31 Best Value Proposition Examples You Wish You Had

Project 6: gRPC and OpenAPI ecosystem

Wechaty has two subsystems for providing the gRPC support: one is wechaty/wechaty-grpc, the other is wechaty/openapi. The related docs page mainly is at Polyglot/OpenAPI as well as other pages that have some OpenAPI related docs.

What we are planning to do is:

1. Improve all OpenAPI related documentation from our docs website https://wechaty.js.org/docs/, especially Polyglot/OpenAPI.
2. Improve READMEs from both wechaty/wechaty-grpc and wechaty/openapi
3. Improve the code when necessary for improving the docs in the repository wechaty/wechaty-grpc and wechaty/openapi

Project 7: Volunteering

Volunteers are in charge of helping the organization mentors to manage the GSoD’21 program, which means that the volunteer team has been authorized to mentor the technical writers on behalf of the mentors as long as the decisions are made by the volunteer team, to improve our GSoD’21 outcome for our community.

The most important roles for the volunteers are:

1. Make sure we are following the Google Developer Documentation Style Guide
2. Make sure we are following the Documentation System
3. Make sure we are following the Organization administrator guide and performing Organization administrator responsibilities
4. Organize team activities as usual (review/approve/meetings/blogs/evaluations/reports)
5. Make decisions on behalf of mentors when necessary for good

Grants

The grants from Google will be split as following:

1. Tutorials: $5k
2. How-to guides: $1k
3. References: $1k
4. Explanations: $1k
5. Landing page with value proposition: $1k
6. gRPC and OpenAPI ecosystem: $1k

The volunteers will get stipends $500 for each.

1. Base grant

The base grants will be the 80% of the each grant.

2. Performance grant

The performance grants will be the 20% of the each grant.

It will be voted by the writer themselves (who is in the same team) with the volunteers after the project has been finished. The rule is that everyone has 10 points which can be used to vote for the performance grant.

3. Example: performance grant voting

Two writers A and B are working together share a $1k project.

The base grants will be $1,000 * 80% = $800, A and B will share $800 equally, which means that A will get $400 and B will get $400 as well for their base grants.

The performance grants will be $1,000 * 20% = $200. According to the performance grants caculating formula, if we assuming the following vote result, then we will get the following distributing result:

1. Vote from A: A:4 B:6
2. Vote from B: A:7 B:3
3. Final percentage result:
   1. A: (4+7)/20 * 100% = 55%
   2. B: (6+3)/20 * 100% = 45%
4. Final distributing result:
   1. A: 55% * $200 = $110
   2. B: 45% * $200 = $90

In our practice we need to add C and D which is our volunteers, that’s it!

4. Thank-you bonus

The “Thank-you bonus” is for those GSoD’21 technical writers who has not been selected in the year 2021 and meet the following requirements:

1. has submitted qualified proposal before the deadline (May 1st)
2. has submitted PR for improving the Wechaty docs and has been merged.

For those technical writers, we have prepared $20 for thank you for the interest in participating in Wechaty GSoD’21, and we hope you will join us in the coming GSoD’22.

The Thank-you bonus will be distributed after we have submited the final report to Google and received the second grants from GSoD’21.

We will prepare a Google Form for collecting the payment information, so please stay tuned and remember to come back to us then!

6. Performance bonus

The performance bonus is an additional $1,000.00 bonus which is for everyone from our technical writer team!

The rule is simple:

1. Wechaty organization will make a budget of $1,000.00 for this performance bonus
2. Everyone in our team will have 10 points to vote other teams (skip their own team)
3. Volunteers and mentors will vote with the same rule
4. All team share $1,000.00 by the points they get

For example, we have two team A and B:

1. Vote from A: A:4 B:6
2. Vote from B: A:7 B:3
3. Vote from Volunteer 1: A:4 B:6
4. Vote from Volunteer 2: A:7 B:3
5. Vote from Mentor 1: A:4 B:6
6. Vote from Mentor 2: A:7 B:3
7. Final percentage result:
   1. A: (4+7+4+7+4+7)/60 * 100% = 55%
   2. B: (6+3+6+3+6+3)/60 * 100% = 45%
8. Final distributing result:
   1. A: 55% * $1,000 = $550
   2. B: 45% * $1,000 = $450

In our practice we need to add C, D, and E which are all of our projects (volunteers team will be included as well).

That’s it!

Wechaty GSoD’21 selected technical writers

Here we’d like to announce that the Wechaty GSoD’21 selected technical writers, they are:

1. Souvik Biswas and Shwetal Soni for Create easy to learn tutorials for beginner users of Wechaty (team proposal)
2. Vasvi Sood and Abhishek Jaiswal for Improve the How-to guides section (team proposal)
3. Shraddha Vasant Prasad and Soumi Bardhan for Improve the References section (team proposal)
4. Mukosa Joseph Mawa and Chris Estepa for Improve the Explanations (and Introduction) sections (team proposal)
5. Sajen Sarvajith k and Arnab Saha for Reconstruct Wechaty homepage(landing page) with value proposition (team proposal)
6. Rajiv Ranjan Singh to Improve the gRPC and OpenAPI ecosystem (proposal)
7. Rohitesh Kumar Jain and Simin Liao (廖思閔) for Volunteering (team proposal)

Welcome the above 13 technical writers onboarding, it’s so great to have you all in our Wechaty organization community, cheers!