diff --git a/docs/_docs/season_of_docs.md b/docs/_docs/season_of_docs.md new file mode 100644 index 00000000000..a0d22c5b529 --- /dev/null +++ b/docs/_docs/season_of_docs.md @@ -0,0 +1,114 @@ +--- +category: documentation +--- + +# 2020 Season of Docs + +![Google Season of Docs](https://developers.google.com/season-of-docs/images/logo/SeasonofDocs_Logo_SecondaryGrey_300ppi.png "Season of Docs") + +This year the gRPC-Gateway is participating in the [Google Season of Docs](https://g.co/seasonofdocs). +We're excited to see what contributions this will bring to our documentation. + +## Project details + + - Organization name: **gRPC-Gateway** + - 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 + common use cases: + - When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API + to old users. + - When a user wants to expose an existing gRPC API to a JSON/HTTP API audience. + - When quickly iterating on an JSON/HTTP API design. + - Website: https://grpc-ecosystem.github.io/grpc-gateway + - Repo: https://github.com/grpc-ecosystem/grpc-gateway + - Project administrators and mentors: + - Johan Brandhorst (@johanbrandhorst) + - Andrew Z Allen (@achew22) + +## Project Ideas + +### Refactor the existing docs site + +Our existing docs site (this site!) is decidedly starting to look a bit dated. We'd love to +have a new version with some updated styling and a better structure. The existing content +could be preserved and just reused with a fresh new look, or we could rewrite much of it. + +It's currently rendered from Markdown using [Jekyll](https://jekyllrb.com/). +[The source code](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/docs) +for the site is part of the main repo. + +We the best way to do this would be to have someone who is unfamiliar with the project +try to use the current material and note anything that was unclear and that they couldn't +easily find with our existing docs. + +Material: + - [The current site](https://grpc-ecosystem.github.io/grpc-gateway/) + - [Jekyll](https://jekyllrb.com/) which powers the site now. + - [The source code](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/docs) for the site today. + - [The project README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md) which + contains an intro to the project. + +### Rewrite the README with a better intro and examples + +The README has evolved since the start of the project and could do with a rewrite from +first principles. The README is the first thing our prospective users see, and it should +quickly and concisely answer the most important questions for our users. + + - What problems can the gRPC-Gateway solve? + - How do I use the gRPC-Gateway? + - What does a complete example look like? + - Where can I find more information about using it? + - Where can I learn more about the technologies the gRPC-Gateway is built on? + - How do I submit an issue report or get help? + +Material: + - [The current README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md). + +### Create a tutorial for the docs site + +We'd like to be able to point to a tutorial for one of the common use cases of the project. +The ones mentioned in the project details are the primary use cases we advertise: + + - When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API + to old users. + - When a user wants to expose an existing gRPC API to a JSON/HTTP API audience. + - When quickly iterating on an JSON/HTTP API design. + +It could be a single or several blog posts on our docs site, or another site, like medium. + +### Improve the "customize your gateway" section of the docs + +This is where we've collected a lot of the little tips we've developed with +users that don't quite fit in the main README or documentation. It would be great +to have a look over this and add detail where possible and generally structure it +a bit better. Maybe it could be rewritten as a FAQ that details solutions to common issues? + +Material: + - [The customize your gateway page](https://grpc-ecosystem.github.io/grpc-gateway/docs/customizingyourgateway.html) + +### Improve the contributors guide + +This is currently split between +[CONTRIBUTING.md] +and the [issue template](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/ISSUE_TEMPLATE.md). +Both of these are a little ad-hoc and could do with a fresh pair of eyes. + +Material: + - [Current CONTRIBUTING.md](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CHANGELOG.md) + - [Current issue template](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/ISSUE_TEMPLATE.md) + +### Write a v2.0.0 migration guide + +We're planning on making a v2 release of the project, which will have some backwards-compatibility breaking changes. +We need to write a migration guide so that users know what to expect when upgrading their deployments. + +This should include: + + - A list of all the breaking changes and their consequences for the user. + - For each breaking change, a guide to how their systems may need to be changed. + +Currently the scope of the v2 release is not entirely known, as it is still in progress, but we will +endavour not to make too many breaking changes as that will discourage users from upgrading. + +Material: + - [v2 Tracking issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/1223)