My second Google Season of Docs, this time with Wechaty (opens in a new tab) on a project called Improve the gRPC and OpenAPI ecosystem. Every pull request was merged and the project finished on scope.
Wechaty is a conversational RPA SDK for chatbot makers — you write bot logic once and it runs across a range of messaging platforms. The gRPC layer underneath it is how the SDK talks to those platform-specific implementations, and it was under-documented relative to how central it is.
Coming into this after the gRPC-Gateway project the year before meant I already knew the gRPC and OpenAPI side. What was new was the community.
What was different this time
The 2020 project was mostly me and two mentors in a Slack channel. Wechaty runs on a much larger cadence: weekly video meetings with everyone present, each one written up as a public blog post on the Wechaty site. Eleven of them over the program.
| Meeting | Written up | Group photo |
|---|---|---|
| Kickoff — technical writers announced | Meeting 0 writeup (opens in a new tab) |  |
| Week 1 | Meeting 1 writeup (opens in a new tab) |  |
| Week 2 | Meeting 2 writeup (opens in a new tab) |  |
| Week 3 | Meeting 3 writeup (opens in a new tab) |  |
| Week 4 | Meeting 4 writeup (opens in a new tab) |  |
| Week 5 | Meeting 5 writeup (opens in a new tab) |  |
| Week 6 | Meeting 6 writeup (opens in a new tab) |  |
| Week 7 | Meeting 7 writeup (opens in a new tab) |  |
| Week 8 | Meeting 8 writeup (opens in a new tab) |  |
| Week 10 | Meeting 10 writeup (opens in a new tab) |  |
NOTE
Publishing a public writeup of every internal meeting seemed like overhead when I first encountered it. It is not. It means anyone can catch up on months of decisions without asking, contributors in other timezones are never locked out of context, and the project has a searchable record of why things were decided rather than just what was decided. It is the cheapest documentation a project can produce and most projects skip it.
What I worked on
The project covered the documentation around Wechaty's gRPC and OpenAPI surface — how the SDK's service definitions map to the HTTP API, and how someone building a bot actually gets from a proto file to a working endpoint. The GSoD-2021 repository (opens in a new tab) has the full record of the work.
Along the way I picked up the parts of the Wechaty stack I had not touched before: Docusaurus for the docs site, JSX, and progressive web apps. The gRPC, Go, and Swagger UI side was familiar ground from the previous year, which meant I could spend the time on the writing rather than on learning the tooling.
What I took from it
Doing this twice made the difference between the two years obvious. In 2020 I learned how to document a tool. In 2021 I learned how a distributed community keeps itself coherent — the meeting notes, the public decision record, the habit of writing things down for people who are not in the room. The documentation I produced was better the second time mostly because the process around it was better.
Thanks to my mentors Huan LI (opens in a new tab) and Li Jiarui (opens in a new tab), and to Simin Liao (opens in a new tab) and Rohitesh Kumar Jain (opens in a new tab) who volunteered their time on reviews. The weekly meetings were well run and never felt like a status check, which is harder to pull off than it sounds.