1---
2category: documentation
3name: 2020 Season of Docs
4---
5
6# 2020 Season of Docs
7
8
9
10This year the gRPC-Gateway is participating in the [Google Season of Docs](https://g.co/seasonofdocs).
11We're excited to see what contributions this will bring to our documentation.
12
13## Project details
14
15 - Organization name: **gRPC-Gateway**
16 - Organization description: The gRPC-Gateway brings the power and safety of designing APIs with Protobuf and gRPC to the JSON/HTTP API world. It has several
17 common use cases:
18 - When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API
19 to old users.
20 - When a user wants to expose an existing gRPC API to a JSON/HTTP API audience.
21 - When quickly iterating on a JSON/HTTP API design.
22 - Website: https://grpc-ecosystem.github.io/grpc-gateway
23 - Repo: https://github.com/grpc-ecosystem/grpc-gateway
24 - Project administrators and mentors:
25 - Johan Brandhorst (@johanbrandhorst)
26 - Andrew Z Allen (@achew22)
27
28## Project Ideas
29
30### Refactor the existing docs site
31
32Our existing docs site (this site!) is decidedly starting to look a bit dated. We'd love to
33have a new version with some updated styling and a better structure. The existing content
34could be preserved and just reused with a fresh new look, or we could rewrite much of it.
35
36It's currently rendered from Markdown using [Jekyll](https://jekyllrb.com/).
37[The source code](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/docs)
38for the site is part of the main repo.
39
40We the best way to do this would be to have someone who is unfamiliar with the project
41try to use the current material and note anything that was unclear and that they couldn't
42easily find with our existing docs.
43
44Material:
45 - [The current site](https://grpc-ecosystem.github.io/grpc-gateway/)
46 - [Jekyll](https://jekyllrb.com/) which powers the site now.
47 - [The source code](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/docs) for the site today.
48 - [The project README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md) which
49 contains an intro to the project.
50
51### Rewrite the README with a better intro and examples
52
53The README has evolved since the start of the project and could do with a rewrite from
54first principles. The README is the first thing our prospective users see, and it should
55quickly and concisely answer the most important questions for our users.
56
57 - What problems can the gRPC-Gateway solve?
58 - How do I use the gRPC-Gateway?
59 - What does a complete example look like?
60 - Where can I find more information about using it?
61 - Where can I learn more about the technologies the gRPC-Gateway is built on?
62 - How do I submit an issue report or get help?
63
64Material:
65 - [The current README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md).
66
67### Create a tutorial for the docs site
68
69We'd like to be able to point to a tutorial for one of the common use cases of the project.
70The ones mentioned in the project details are the primary use cases we advertise:
71
72 - When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API
73 to old users.
74 - When a user wants to expose an existing gRPC API to a JSON/HTTP API audience.
75 - When quickly iterating on an JSON/HTTP API design.
76
77It could be a single or several blog posts on our docs site, or another site, like Medium.
78
79### Improve the "customize your gateway" section of the docs
80
81This is where we've collected a lot of the little tips we've developed with
82users that don't quite fit in the main README or documentation. It would be great
83to have a look over this and add detail where possible and generally structure it
84a bit better. Maybe it could be rewritten as a FAQ that details solutions to common issues?
85
86Material:
87 - [The customize your gateway page](https://grpc-ecosystem.github.io/grpc-gateway/docs/customizingyourgateway.html)
88
89### Improve the contributor's guide
90
91This is currently split between
92[CONTRIBUTING.md](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md)
93and the [issue templates](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/.github/ISSUE_TEMPLATE).
94Both of these are a little ad-hoc and could do with a fresh pair of eyes.
95
96Material:
97 - [Current CONTRIBUTING.md](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md)
98 - [Current issue templates](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/.github/ISSUE_TEMPLATE)
99
100### Write a v2.0.0 migration guide
101
102We're planning on making a v2 release of the project, which will have some backwards-compatibility breaking changes.
103We need to write a migration guide so that users know what to expect when upgrading their deployments.
104
105This should include:
106
107 - A list of all the breaking changes and their consequences for the user.
108 - For each breaking change, a guide to how their systems may need to be changed.
109
110Currently, the scope of the v2 release is not entirely known, as it is still in progress, but we will
111endeavour not to make too many breaking changes as that will discourage users from upgrading.
112
113Material:
114 - [v2 Tracking issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/1223)
View as plain text