Between August and December 2020 I rebuilt the documentation site for gRPC-Gateway (opens in a new tab) as part of Google Season of Docs. The result is live at grpc-ecosystem.github.io/grpc-gateway (opens in a new tab).
gRPC-Gateway is a protoc plugin that reads gRPC service definitions and generates a reverse-proxy server translating a RESTful JSON API into gRPC. It is a genuinely useful thing that was, at the time, hard to get started with — which is what the project set out to fix.
What shipped
All the work landed across five pull requests. My mentors suggested I work in a fork and open pull requests once a substantial chunk had accumulated, rather than one per change — a good call given how much of it was file moves that would have been unreviewable in isolation.
| Pull request | What it contains |
|---|---|
| #1786 (opens in a new tab) | New Jekyll theme and the migrated site — weeks 1 to 5 |
| #1829 (opens in a new tab) | The tutorials section: hello world and arithmetic server — weeks 6 to 10 |
| #1844 (opens in a new tab) | Additional FAQ entries |
| #1845 (opens in a new tab) | New architecture diagram |
| #1851 (opens in a new tab) | Documentation refactor across existing files |
Three things I had planned did not make it: automated changelog generation from the repository, a release-notes section, and a commenting system. The first two were deprioritised in favour of the tutorials, which mattered more; the third I am no longer convinced was a good idea for a docs site.
How it went, roughly by month
Community bonding (August). Read the existing documentation end to end and wrote down every gap I found. That list became the project timeline. Also got onto the gRPC-Gateway Slack, which turned out to matter more than anything else — most of my questions were answered there in minutes.
Theme and migration (September). Compared documentation-focused Jekyll themes across a range of projects, wrote up the comparison, picked one, deployed it to my fork, and moved all existing content over. Then drafted the landing page.
Learning the tool (October). This is the part that changed the project. I built a working gRPC-Gateway installation with a Go backend, then a small arithmetic gRPC service on top of it, taking notes on every step that confused me. Those notes became the installation guide.
Tutorials (late October to November). Wrote the tutorials section proper: generating gRPC stubs with both buf and protoc, writing protos with HTTP annotations, and a hello world program built up from an empty main.go through a net/http handler to a full gateway, verifiable with one cURL command.
Cleanup (late November). More FAQ entries, a new architecture diagram to replace the old one, and a pass over every file for indentation, grammar, typos, and broken links.
TIP
The single most useful thing I did was install and use the tool as a beginner while writing the beginner's guide. Every place I got stuck was a place the documentation was wrong or missing, and I only noticed because I had not yet built up the assumed knowledge that makes those gaps invisible. If you are documenting something you already know well, find a way to make yourself a novice again — the gaps are obvious from there and nearly impossible to see from anywhere else.
What I learned
The technical side — gRPC, protobuf, Jekyll, Docker, Postman, Swagger UI, running Go servers — was the easy part, and mostly a matter of reading. The harder lesson was about sequencing: I spent the first month on theme selection and migration because it felt like the foundational work, when the tutorials were what users actually needed. Infrastructure feels like progress because it is measurable. It usually is not the thing that matters.
Ten fortnightly meetings over the program, all in IST, all half an hour. Short and regular beat long and occasional.
Thanks to my mentors Johan Brandhorst-Satzkorn (opens in a new tab) and Andrew Z Allen (opens in a new tab), who reviewed a large amount of prose carefully and were consistently clear about what was and was not worth doing — including talking me out of a couple of things. The GSoD-2020 repository (opens in a new tab) has the full record.