loading...
Cover image for Community Bonding with the GraphQL Foundation for Google Season of Docs

Community Bonding with the GraphQL Foundation for Google Season of Docs

carolstran profile image Carolyn Stransky Originally published at workwithcarolyn.com ・4 min read

Google Season of Docs is a 3-month program that connects experienced technical writers with an open-source community. I was accepted into the 2020 program to work with the GraphQL Foundation. This post is part of a series intended to give insight to technical writers considering future Season of Docs cohorts.

The first month of Season of Docs is known as the community bonding phase. According to Google, this period is intended to help technical writers prepare to contribute to the mentoring organization once the program is in full swing.

During this phase, I was employed full-time and dedicated about 10 hours per week to the GraphQL Foundation.

Some organizations will have clear expectations for what they’d like you to complete during this phase. Others, like the GraphQL Foundation, give you more freedom to decide how you want to get to know the community. I chose the following activities with the help of my assigned mentor, Ivan Goncharov.

Attempted to figure out the organization structure

Part of the community bonding phase is becoming familiar with existing practices and processes. I’ve been in the GraphQL ecosystem for a while - creating side projects, giving talks, and even using it at work sometimes. My previous involvement was actually a large part of why I was selected.

But getting involved with the Foundation has been really different than using the specification. There’s a hierarchy and internal politics. GraphQL's history (having been incubated at Facebook) also influences the existing setup. So figuring out how decisions are made and who controls which aspect of GraphQL is confusing.

I tried to decipher all of this through meetings with my mentor, watching recordings of the past working group meetings, and creating my own mind map of the Foundation structure. Once I’m more confident with it, I’ll share it in a future post.

Triaged issues and pull requests

Within the first week, I was made a member of the GraphQL organization on GitHub and given triage access to graphql.github.io (the repository that contains the base code for the GraphQL website and documentation).

For those who aren’t familiar with triaging, this can include:

  • Creating new labels to appropriately tag issues
  • Reviewing code on open pull requests
  • Reproducing and confirming any reported bugs
  • Closing anything that’s irrelevant or duplicates

If I ran into process gaps, I opened my own issues or flagged it to Ivan. Many of these issues and pull requests hadn’t been touched in years, so it took time to figure out why and how to move forward.

While my triage access was limited to the documentation repository, I started becoming familiar with the other repositories within the GraphQL organization. I focused on repositories that would be relevant to my project, like graphql-spec and an existing faq. Along the way, I’d note anything that might be useful for me in the future.

Helped with the Gatsby migration

Earlier this year, there were discussions about migrating the GraphQL website from custom scripts to Gatsby/Next.js. This migration was approved before I became involved with the Foundation and now it’s a priority to get this done.

Due to my limited availability during this phase, the help I offered was limited to reviewing the existing pull request by saihaj and planning the steps for the migration. We settled on merging it into its own gatsby branch and then open separate pull requests to fix the remaining issues. Which is part of what I’m currently working on!

Want to help us out with this migration? Check out and claim one of the remaining issues.

Aligned on expectations for my project

During this phase, I also had one meeting with my mentor to discuss the new Frequently Asked Questions (FAQ) page that I’ll build. We didn’t dig deep, but we did refine the project plan, agree on initial milestones, and figured out what potential blockers I may face.

What happens next?

Now that the bonding is over, it’s time to get to work on documentation development 🚀

If you’re interested, check out my original project proposal and watch out for my post in the GraphQL Foundation blog.

Posted on by:

carolstran profile

Carolyn Stransky

@carolstran

Software developer and sometimes still a journalist (she/her)

Discussion

markdown guide