Google Season of Docs 2020 Participant: Carolyn Stransky

Carolyn Stransky is a frontend developer and journalist based in Berlin, Germany. She is selected for Google Season of Docs 2020 - GraphQL Foundation under the mentorship of Ivan Goncharov. In this post, she will share her plans on how she is going to spend the next couple of months contributing to the GraphQL Foundation.

When I first heard about GraphQL three years ago, I thought that it was a programming language that constructed charts or plotted points on graphs. After building my first application with GraphQL, I would have categorized it as React-specific tooling, like Redux or React Router. Months later, I was still convinced it was just another Twitter-fueled programming trend.

Looking back now, it’s clear that my initial perceptions of GraphQL were incorrect… but they weren’t uncommon.

Learning a new technology comes with a lot of questions - and GraphQL is no exception. There are so many misconceptions about what GraphQL is and how it can be used. And I wasn’t the only GraphQL newbie holding on to those same, inaccurate beliefs.

After gaining a solid understanding of what GraphQL really is, I started giving presentations at conferences about how difficult I found the learning process (literally the talk title was Life is hard and so is learning GraphQL). This talk was cathartic, both for me and the audiences I was presenting to. Through my research, I also realized that while graphql.org thoroughly covers the core concepts, it doesn’t directly address some of the questions you face as a new learner.

Fortunately, GraphQL has evolved enough that the information is out there and available. It’s more a matter of finding it because that information is scattered throughout various resources and programming communities. That’s why I was excited to see a Frequently Asked Questions (FAQ) page as one of the proposed Season of Docs projects. And as someone who has openly critiqued the GraphQL documentation, I wanted to play a part in actively improving them.

There are two main goals behind this FAQ page:

1. Build a centralized resource for everyone. As of now, much of the GraphQL ecosystem is focused on JavaScript due to the early ties with Relay and React. But GraphQL is for everyone, regardless of programming language, so this resource should be too. To ensure this, the FAQ content will be framework agnostic and vendor-neutral.
2. Become a truly community-owned resource. GraphQL was initially passed down from Facebook, but it’s no longer maintained solely by Facebook. This should be a resource that everyone is welcome to contribute to and the community feels empowered to change and grow. That way, common questions won’t be left unanswered.

The plan for exactly how to tackle this page will morph and evolve throughout the next two and a half months. My hope, though, is that keeping these goals in mind will lead to a new resource that will help both newcomers and seasoned GraphQL users thrive.

In preparation for the documentation development part of Season of Docs, I became familiar with the repository behind graphql.org by triaging issues and reviewing open pull requests. I also helped with the ongoing migration to Gatsby because I’ll be building the new FAQ page in Gatsby (there are still open issues if you want to contribute). You can read more details about the community bonding phase on my blog.

The next step is to create the inaugural batch of FAQ content. This will be about 10-15 questions sourced from various areas of the Internet and in consultation with prominent GraphQL teachers. Once those are complete with thorough answers and built into the new Gatsby site, I’ll get feedback from the community (that’s you) and continue to iterate on the content, design, layout - everything!

If you have opinions or would like to follow the project’s progress, open an issue or lurk around the website repository.

– Carolyn Stransky, GSoD 2020, Graphql Foundation